docs(self-host): agent runner docs, hosting layout, and image reorg - #5301
Conversation
dosubot
Bot
added
the
size:XXL
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
🌙 Overnight — ready for review. Restructures the self-host docs + hosting layout for the agent-studio pivot: 7 new agent-execution pages and a holistic self-host sidebar (no |
|
Pushed Missing variables added (the runner reads all of these; none were in the env examples)
Consolidation. Runner config was spread across four sections of every env example (Core endpoints, Agenta - Agent, Sandbox (agent runner), daytona). It is now one The Resolved questions
Snapshot rename to Verification. Every Heads-up unrelated to this PR: three failures in |
| @@ -1,5 +1,6 @@ | |||
| --- | |||
| title: Configure SSO Authentication | |||
| slug: /self-host/guides/configure-sso | |||
There was a problem hiding this comment.
Any reason we are adding slugs here?
There was a problem hiding this comment.
Answered rather than removed: the file moved (guides/05-configure-sso.mdx → access-control/01-configure-sso.mdx), and the slug pins the public URL /self-host/guides/configure-sso so existing links, bookmarks, and search results keep resolving. Same reason on the other two moved pages. No slug was added to a page that did not move.
I added the rule to write-docs §0 so this is not guesswork next time: a slug exists to preserve a URL, never because other pages have one.
|
|
||
| ```bash | ||
| SUPERTOKENS_EMAIL_DISABLED=true | ||
| AGENTA_ACCESS_EMAIL_DISABLED=true |
There was a problem hiding this comment.
It is a fix. The page documented SUPERTOKENS_EMAIL_DISABLED, which is the legacy name. api/oss/src/utils/env.py:174 reads AGENTA_ACCESS_EMAIL_DISABLED first and only falls back to SUPERTOKENS_EMAIL_DISABLED, and all four env examples ship the AGENTA_ACCESS_* name. So the docs were pointing readers at the deprecated variable. Kept the change.
mmabrouk
left a comment
mmabrouk
left a comment
There was a problem hiding this comment.
I don't agree with the organization of the files, at least when I look at them in the UI. I think we need to clarify what is a tutorial, what is a how-to, and what is a concept. Right now, everything is in the same organization. Let's chat about this before making any changes.
| @@ -1,5 +1,6 @@ | |||
| --- | |||
| title: Restrict Sign-ups and Organization Creation | |||
| slug: /self-host/guides/restrict-organization-creation | |||
There was a problem hiding this comment.
Same as on the SSO page: this file moved from guides/06-restrict-organization-creation.mdx, and the slug keeps /self-host/guides/restrict-organization-creation working. Not gratuitous.
| @@ -1,5 +1,6 @@ | |||
| --- | |||
| title: Dynamic Access Controls | |||
| slug: /self-host/dynamic-access-controls | |||
There was a problem hiding this comment.
Same: this file moved from self-host/04-dynamic-access-controls.mdx, and the slug keeps /self-host/dynamic-access-controls working.
| This page answers the first question a self-hosting team asks: is it safe to let users run agents | ||
| on my deployment? The short answer is that it depends on which sandbox provider you enable. | ||
|
|
||
| ## Local runs are not an isolation boundary |
There was a problem hiding this comment.
This is not clear at all. Please don't use weird sentences as titles.
There was a problem hiding this comment.
Instead, just have call it local runs
There was a problem hiding this comment.
Fixed. Headings are plain labels now: Daytona, Local runs, and under each: The boundary, What crosses into a Daytona sandbox / What crosses into a local run, What ... runs share with each other, When to use it. No claims or clauses as headings, here or on the other pages.
There was a problem hiding this comment.
Renamed. The section is Local runs.
| --- | ||
|
|
||
| This page answers the first question a self-hosting team asks: is it safe to let users run agents | ||
| on my deployment? The short answer is that it depends on which sandbox provider you enable. |
There was a problem hiding this comment.
This is feedback for the whole page. I think it's easier to do it this way:
- There is no need to add descriptions that are meaningless. For example, in this first sentence, it's good to start with the context, but why are you saying it's the first question? That's an assumption you're making. This phase answers the question of whether it's safe to let users run agents on my deployment. The short answer is: it depends on which sandbox provider you enable. For local, it is not safe. Use this only blah blah blah. For Daytona, it is safe, and see the details below. Start with Daytona and explain how it works, and make sure to add a clear warning. With these warning elements that we have in docuservice, you should not use local elsewhere in the documentation. You should only use local brands for your local machines or within your teams. When it's safe, the agent has access to environment variables that are in the book. Will composite really make sure it is not for production? It is just for internal workflows, and here are the things: if you want isolation, use Daytona.
- Another warning.
That's basically it, and then explain things in simple ways.
There was a problem hiding this comment.
The second thing is to start with context. Give the context that you can configure Agenta to work with this, and we're gonna add multiple runners for local deployment. Use this. It's simpler. It works for kind of your internal use cases for something external use sandboxes.
There was a problem hiding this comment.
Rewrote the page on this structure:
- Context first. Opens with: Agenta runs agent code in a sandbox; a deployment picks the provider (Daytona cloud sandbox, or local inside the runner container); the choice decides whether it is safe to let other people run agents. Then one sentence saying Daytona isolates every run and local runs do not, with the links to the config page and the Daytona how-to. No "first question teams ask" assumption.
- Daytona first, then local runs, with mirrored subsections:
The boundary→What crosses into ...→What ... runs share with each other→When to use it. - A real
:::warningon the local side ("Local runs are not isolated from each other"), stating the multi-user consequence in concrete terms. - Configuration is one sentence plus a link in the intro, not a section.
There was a problem hiding this comment.
Done. The page now opens with the context (you configure which sandbox provider the deployment runs; local is simpler and runs in the runner container, Daytona isolates each run in the cloud), and points at the runner configuration page for the how.
|
|
||
| ## Local runs are not an isolation boundary | ||
|
|
||
| A local run executes the harness inside the runner container. It shares that container's |
There was a problem hiding this comment.
The things to clarify here are:
- The local run is executed in a runner container that does not have access to anything in your local system unless you mount it explicitly. It does not have any access to any environment variable or any executable outside of that Docker container, where we see the limitations of that.
- However, all agents that are running are running in the same container together with a runner, which means it has access to the files of the other agents. If you mount the Claude thing, it has access to that, and it has access to the environment variables in the runner, which are this and this.
Overall, it's not safe. It will not make it break your system, right? If you have something outside of the container, it cannot touch it. That's very important to say. However, between agents, they might touch things and obviously use the permissions in the agent to make sure that they can use whatever they are supposed to use.
There was a problem hiding this comment.
Rewrote it with exactly those two facts, split into two subsections:
The boundary — the container is a boundary against the host. Agent code cannot read files, environment variables, or executables outside the runner container unless you mounted them in. Mounting a host directory puts it inside the boundary.
What local runs share with each other — every local run executes in the same container, so an agent can read another agent's working directory, the container's environment (naming AGENTA_RUNNER_DAYTONA_API_KEY and AGENTA_RUNNER_TOKEN), and any mounted credential. That is in a :::warning, phrased as the multi-user consequence.
When to use it closes with tool permissions as the way to constrain what an agent may do inside the container.
| filesystem and environment. Agent code in a Daytona run cannot read the runner's process | ||
| environment, its files, or its Daytona provisioning credential. | ||
|
|
||
| Use Daytona when a deployment is multi-user or exposed. |
There was a problem hiding this comment.
Same multi-user, don't match in exposed for the moment.
There was a problem hiding this comment.
Dropped "exposed" everywhere. The condition is stated as: "when more than one person can start runs on the deployment, or when the deployment is reachable by people you do not fully trust". Added the rule to write-docs §0 (use the precise word, not the dramatic one).
|
|
||
| Use Daytona when a deployment is multi-user or exposed. | ||
|
|
||
| ## The enabled-provider list is the posture switch |
There was a problem hiding this comment.
This should be a link on how to run a configuration. It should be mentioned above and mentioned as a context. You can decide which thing: here's how you can do it. Kind of one sentence, it's not a section.
There was a problem hiding this comment.
Done. The "enabled-provider list is the posture switch" section is gone. The intro now has one sentence: enable providers with AGENTA_RUNNER_ENABLED_SANDBOX_PROVIDERS, with links to the runner reference for the syntax and to the Daytona how-to for the setup.
| Sandbox provider 'local' is not enabled on this deployment (enabled: daytona). | ||
| ``` | ||
|
|
||
| ## What crosses into a Daytona sandbox |
There was a problem hiding this comment.
The organization of this document is so bad. Please rethink it and look at the other documents to organize them.
- If you are mentioning what crosses into Daytona Sandbox, make sure that it's nested under Daytona.
- If you have a section about this information, which seems to be interesting, then make sure to have a parallel section for the parallel thing, which is local. And please review all other edits using this rule and add it to your memory. Read the skill about how to write docs and update it if it does not mention this. If it mentions this and you did not read it, then read it again and update based on it.
There was a problem hiding this comment.
Reorganized:
- "What crosses into a Daytona sandbox" is now a subsection under Daytona, and it has its parallel on the local side ("What crosses into a local run"). Both are the same table shape.
- Every subsection under Daytona has a counterpart under local runs, in the same order, and Daytona leads.
- Applied the same rule across the other pages in the PR (
Customize the agent runtimeis now Daytona → Local runs with identical subsections; the Daytona how-to now has its parallelRun agents locallypage, which did not exist). - The rule is in
write-docs§0 ("Parallel things get parallel structure"), and I added the further rules I took from your other comments: concrete examples, precise vocabulary, a pointer is a sentence not a section, slugs preserve URLs.
|
|
||
| ## 3. Build a snapshot (recommended) | ||
|
|
||
| Daytona runs start faster from a prepared snapshot that already contains the harness runtimes. |
There was a problem hiding this comment.
Explain what the snapshot is. Have a link to a reference or whatever that says what stuff is within the snapshot. What does this build snapshot do? Mention that you can add other dependencies to the snapshot if you want your agent to have access to these when you use Daytona. Provide some context always.
There was a problem hiding this comment.
Rewrote step 3. It now says what a snapshot is (a prebuilt sandbox image stored in your Daytona account; every sandbox the runner creates starts from one, so whatever it contains is what your agents can run), links the Daytona snapshot docs, and says plainly what the recipe does: it starts from the sandbox base image, which already has Claude Code, Codex, and OpenCode, adds Pi at the version the runner expects plus the FUSE tooling for durable working directories, names the snapshot agenta-agent-sandbox-v1, and sizes each sandbox at 2 vCPU / 4 GB / 5 GB.
It closes by saying you can add your own tools or change the resources, with a link to Customize the agent runtime.
| does not build the custom-code evaluator sandbox. To add your own binaries or dependencies to | ||
| agent runs, see [Customize the agent runtime](/self-host/agent-execution/customize-the-agent-runtime). | ||
|
|
||
| :::warning[Do not reuse the code evaluator's snapshot] |
There was a problem hiding this comment.
Why are you giving this warning? It is a different environment variable. It is a howto. No need to confuse the user.
There was a problem hiding this comment.
Removed. The code-evaluator warning is gone from the how-to. The fact that the two DAYTONA_* sets are different sandboxes, and that the snapshot is not shareable, is stated once in the reference page and once in the env examples, where it belongs.
| session and logs the repair, so runs still work. Building the snapshot avoids that per-sandbox | ||
| install cost. | ||
|
|
||
| The recipe here builds the runner's sandbox. It does not build the runner service image and it |
There was a problem hiding this comment.
Why are you saying this? This is very confusing. Don't mention this. Mention the things that are needed. How would even the user think about custom code evaluator sandboxes? It is not their problem. If you want to have some information, have it in the reference, but this is not in a how-to.
There was a problem hiding this comment.
Removed entirely. Nothing about the code evaluator appears in this how-to any more.
| `AGENTA_RUNNER_DAYTONA_SNAPSHOT` and `AGENTA_RUNNER_DAYTONA_IMAGE` are mutually exclusive. Set a | ||
| snapshot or an image, not both. If you set neither, the runner uses its pinned default artifact. | ||
|
|
||
| If a snapshot or image is missing the pinned Pi runtime, the runner installs it before the |
There was a problem hiding this comment.
Why are we saying, "If it's missing pinit, Pi runtime, whatever"? Just say what the snapshot does: it installs Pi, it installs Claude. You can use it to add other things. Here is how it works: run it as it is. If you want to modify, do this, for example, but no need to provide unclear. Why do I need to know this? It's why I'm gonna install this, create this sandbox with this ticket script that you gave me, so why are you telling me the image will be missing Pi? It won't be missing Pi because I just followed what you said. It's like you're writing the documentation for a developer within the team. You're writing the documentation for an external user that is only reading your documentation and doesn't know anything else. Don't confuse them with other information, and please read the rest of the documentation and add this information. Again, update your memory. If you don't have this, update the skill for writing documentation, and review the whole documentation based on this.
There was a problem hiding this comment.
Removed both the "if the image is missing Pi" warning and the matching troubleshooting entry. The step now just says what the recipe does and how to run it. A reader who followed it does not have a snapshot missing Pi.
|
|
||
| ## 4. Make the store reachable | ||
|
|
||
| Daytona sandboxes run in the cloud and mount durable working directories over the public |
There was a problem hiding this comment.
This is quite confusing. Here again, you provide the context, and you say, "Depending on the situation, if you are using S3 mounts, if you are using local development, if you are using whatever you need to do this." When you say, "enable the wistunnel profile," how do I do this? Provide me with real steps I can run.
Provide:
- Context. This is the problematic situation so that I know whether it is something relevant to me.
- Instructions on how to solve this.
- Maybe references if I need help to get more information.
Again, this is a general rule about how to do these things. Always, this thing: what's the context? Think about the reader. The reader needs to understand the context to see if this is relevant to the need to care, and then they need to have clarification whether it's relevant to them. They need to make the decision whether I should do something. Is it actionable for me? They need clear instruction on how to do it, and finally they need some references if it's complicated so that they understand more about the concept or the references or whatever.
Again, add this to your memory. Update the docs. Obviously, these guidelines make sense when it's complicated. No need to overdo it, and also update the writing docs skills to include this guideline.
There was a problem hiding this comment.
Rewrote step 4 on the four beats:
- Context. Agents keep files across turns in a working directory in the durable store. A Daytona sandbox mounts it from the cloud, so it reaches the store over the public internet. If the endpoint is not publicly reachable, working directories become ephemeral and the runner logs a mount-degradation warning.
- Is this me. It applies when
AGENTA_STORE_ENDPOINT_URLpoints at a host the internet cannot resolve: a Compose service name likehttp://seaweedfs:8333(the default for the bundled store),localhost, or a private IP. Railway and Kubernetes with public ingress: skip the step. - Instructions. Two runnable options: point
AGENTA_STORE_ENDPOINT_URLat a public S3 endpoint, or tunnel the bundled store (get an ngrok authtoken, putNGROK_AUTHTOKENin the env file, start withrun.shwhich enables thewith-tunnelprofile by default, or pass--profile with-tunnelto Compose directly), plus the command to verify the tunnel is up. - References. Links to the store reference.
| A first run creates a sandbox in your Daytona account. Later turns reuse a warm sandbox until it | ||
| stops or is deleted. See [warm sessions and lifecycle](/self-host/agent-execution/runner-configuration). | ||
|
|
||
| ## Personal subscriptions are not supported on Daytona |
There was a problem hiding this comment.
This is another section. this is :::info
Here, we don't do value judgment. We just explain that personal subscriptions are done with mounts and local. However, obviously, this is not feasible in Daytona, so we are not uploading the subscription to Daytona. If you want to use your credential, then you need to use it on your local machine. It's for personal use, something of this.
There was a problem hiding this comment.
Now a :::info at the end of the smoke test, with no value judgment: a personal Pi, Claude, or ChatGPT login authenticates a harness through a directory mounted into the runner container; Agenta does not upload it to a Daytona sandbox, so Daytona runs use a model API key; link to Use your own subscription.
| sandbox. Use a managed model key for Daytona runs. See | ||
| [Use your own subscription](/self-host/use-your-own-subscription). | ||
|
|
||
| ## Troubleshooting |
There was a problem hiding this comment.
For troubleshooting, please find a pattern. Maybe in other places of documentation we do it, so if we're using collapsible, then use collapsible. Don't reinvent a pattern for each thing.
There was a problem hiding this comment.
Adopted the pattern already used in the docs (for example administration/access-control/02-sso.mdx): ## Troubleshooting, then an ### heading per symptom, then **Cause:** and **Solution:**. Applied the same shape on this page, on the runner reference, and on the new Run agents locally page, so the three read the same.
| sidebar_position: 4 | ||
| --- | ||
|
|
||
| Agents sometimes need tools that are not in the default runtime: a browser like Chromium, the |
There was a problem hiding this comment.
This is good. You started with context.
There was a problem hiding this comment.
Kept the opening, and extended it to cover the other two things this page now answers (extra folders, and more CPU/memory/disk).
| Agents sometimes need tools that are not in the default runtime: a browser like Chromium, the | ||
| `gh` CLI, a custom certificate, or an extra system package. | ||
|
|
||
| Where you add them depends on where the agent code runs. This is the part teams get wrong. |
There was a problem hiding this comment.
Don't assume something about the reader. This is the part that teams get wrong. This is an assumption. Who the hell are you to assume that the team is getting something wrong? Just be clear: think about the reader.
If the reader is reading this, why do they care that teams get it wrong? What they care about is the context. I need this. This is good, and then they need to understand what it's done. This page explains how to add these tools, and then the thing you need to care about depends on whether you're local or in Daytona. The way we do it will be different.
You provide these two things:
- They will jump to local directly.
- They jump to Daytona.
You also provide context that this is configurable, so you can see: jump to the other page if you miss the information that you need to configure local in Daytona. You have two, in general, very parallel ways of doing it with the same organization, like Daytona, and then subitems, subsections, and local subsections. You try to keep these always in parallel so it's kind of the same information here and there, and you start with Daytona.
There was a problem hiding this comment.
Deleted "This is the part teams get wrong". The intro now states the fact and lets the reader pick their path: Daytona runs execute in a cloud sandbox, so you customize the snapshot; local runs execute in the runner container, so you customize the runner image. It adds the pointer for someone who does not know which one they run ("check AGENTA_RUNNER_ENABLED_SANDBOX_PROVIDERS in the runner reference"), and the page is then two mirrored sections, Daytona first: Add tools and dependencies, Add folders, Sandbox resources / Container resources.
|
|
||
| Read [How agents run](/self-host/agent-execution/how-agents-run) if that distinction is new. | ||
|
|
||
| ## Add dependencies for Daytona runs |
There was a problem hiding this comment.
As mentioned above, it's a section for Daytona, and then subsections. Now, context here is how you add the dependencies to Daytona. Maybe provide an example. When you say, "Okay, the dependency," for example, I don't know, you want to add gh or whatever, or Chromium or whatever. You just kind of provide it something that makes sense, and you save this snapshot and name it. Probably don't name it the same name that we use per default Agenta agents and bucks, so that it's clear, and then you point to it, right?
There was a problem hiding this comment.
Done. The Daytona path is now: copy the recipe, give the snapshot its own name (SNAPSHOT_NAME = "my-agent-sandbox-v1", explicitly so it does not collide with the Agenta default), add your dependencies with a worked example (RUN apt-get install -y gh chromium), build it, then point AGENTA_RUNNER_DAYTONA_SNAPSHOT at your snapshot and recreate the runner.
| AGENTA_RUNNER_DAYTONA_SNAPSHOT=agenta-agent-sandbox-v1 | ||
| ``` | ||
|
|
||
| ## Sandbox size |
There was a problem hiding this comment.
Do we allow editing these environment variables from the outside? If so, why are they not called Agenta Runner Daytona Sandbox CPU? Why are they general? Please update that to have the default at least to the one, obviously these, and then, in explaining these, provide the context. Say we have some defaults. You might need something else. Here's how you can update them.
There was a problem hiding this comment.
You found a real bug. They are read from the environment by build_snapshot.py, so they are operator-facing, and they were named outside the runner namespace. Renamed:
AGENTA_SANDBOX_CPU→AGENTA_RUNNER_DAYTONA_SANDBOX_CPUAGENTA_SANDBOX_MEMORY_GB→AGENTA_RUNNER_DAYTONA_SANDBOX_MEMORY_GBAGENTA_SANDBOX_DISK_GB→AGENTA_RUNNER_DAYTONA_SANDBOX_DISK_GB
in services/runner/images/sandbox/daytona/build_snapshot.py and everywhere they are documented. Grepped the repo: nothing else read the old names.
The section now gives the context (each sandbox gets the CPU, memory, and disk baked into the snapshot), the defaults (2 / 4 / 5), and how to change them.
| DAYTONA_API_KEY=<daytona-api-key> DAYTONA_TARGET=eu uv run build_snapshot.py --force | ||
| ``` | ||
|
|
||
| A new value takes effect only when you rebuild the snapshot, so it never touches sandboxes that |
There was a problem hiding this comment.
This is stupid! Again, think about the user: what do I need to know here? Is it that if I updated the sandbox, then I need to update the environment variable in the runner so that I allow this? You explain it this way: first, update the sandbox and rebuild it. After you rebuild it, you need to update the environment variable for the runner so that they fit. You stop there. You don't give "keep CPU and memory generous." That's your advice. That is obvious. It's not the problem, and it's not your problem. Don't mention sandboxes are running or whatever if you want to have some warning or some info. use :::warning
There was a problem hiding this comment.
Rewritten to exactly that: set the values, rebuild the snapshot, then point the runner at the rebuilt snapshot and recreate it so the two match. Full stop. The "keep CPU and memory generous" advice is gone, and the fact that running sandboxes keep the old values is a :::warning.
| `5` GB leaves a few GB of working headroom on top of the built image. Keep the CPU and memory | ||
| generous, since agents spike during builds and an out-of-memory kill mid-run is a poor experience. | ||
|
|
||
| ## Add dependencies for local runs |
There was a problem hiding this comment.
Use the same structure and organizations for these sections and subsections. If you have a local run, you do it like you try to parallelize the same thing as Daytona, and then you have using Docker compose and using Helm, for example, or you do an m4 using Helm, right?
There was a problem hiding this comment.
Done. Local runs now mirrors Daytona subsection for subsection: Add tools and dependencies, Add folders, Container resources. Each step names the Compose path and the Helm path, so the two deployment surfaces are covered in the same place rather than in separate sections.
|
|
||
| For Helm, set the runner image in your values file under `agentRunner`. | ||
|
|
||
| ## Add project folders for local runs |
There was a problem hiding this comment.
Clearly, subtraction here. Clearly, something that is not for Daytona. Maybe you add an info that it's just for this, for local, not for Daytona. Probably you can also change the information or the data about CPU memory here so that it becomes parallel to Daytona by changing the local compose, and you just can say that you can limit the memory.
There was a problem hiding this comment.
Both parts done. The mount section is local-only and now says so in a :::warning (every local run sees every folder you mount, and a :rw mount is writable by any of them), and I made resources parallel: Daytona gets Sandbox resources (snapshot build variables) and local gets Container resources (CPU and memory limits on the runner service in a Compose override, plus the Helm equivalent).
|
|
||
| ## Add project folders for local runs | ||
|
|
||
| To make extra folders available inside local agent runs, mount them into the runner container |
There was a problem hiding this comment.
Provide an example, for example, giving access to a GitHub repository work tree or some global context in the machine. Mention read and write.
There was a problem hiding this comment.
Added. The example is a repository checkout on the host mounted into the runner (/srv/repos/my-service:/agenta/workspaces/my-service:rw), with :rw explained (agents commit to the worktree) against :ro (read only). The parallel on the Daytona side says a cloud sandbox cannot mount a host directory, so files are copied into the snapshot instead.
| sidebar_position: 5 | ||
| --- | ||
|
|
||
| Every operator-facing runner variable, its default, and where it is set. The runner parses all of |
There was a problem hiding this comment.
Please start with context: what is this? If I read this, what is this? Description is not shown here, so on this page we describe the configuration for blah blah blah, for example.
There was a problem hiding this comment.
Done. The page opens with what it is: the reference for the agent runner, the service that executes agent code either inside its own container (local) or in a Daytona cloud sandbox, listing every operator-facing variable, its default, its Helm path, and the errors an invalid value produces.
| sidebar_position: 0 | ||
| --- | ||
|
|
||
| Agenta is an agent studio. When you self-host, you run the studio and the services that let you |
There was a problem hiding this comment.
No need to say this. If somebody is reading this, the first thing they know is what Agenta is. If it's an overview, the thing I need to care about as a user is: how do I navigate this? Where should I start?
I don't think I care if there is very important information. You can put it in the overview, but other than that, I just want to understand it. It's like:
- Agenta can be self-hosted as Docker Compose.
- It can be self-hosted as Kubernetes.
- You can self-host it so that you use it locally with a local thing, and that allows you to do subscription.
- You can use it in Daytona so that the agent runs in Daytona, and then you provide information.
- Here's where you start, blah blah blah.
- There is an enterprise version.
- Here is the difference.
- You link, obviously.
We write this whole thing. We have regular people, but it should be some sort of very high-level index, not the same as a sidebar with some meta information that allows me to get the general information and the thing I care about. What do I care about?
You can self-host Agenta. It has all the features that are in the cloud, minus the governance feature, and here's the link. I know I can surface it when it's self-hosted to Docker Compose. It requires X memory, X CPU, whatever, if you want to know where to start. Here's the quick start to self-host it. If you want to use your Claude Code subscription, blah blah blah, here's how you do it. If you want to use Daytona, here's how you do it.
Kind of the high level is usually where the general user will go: "Okay, I want to say, first, locally, I want to use my Claude Code subscription, etc." Then you go to a little bit more stuff, but then that's it, right? You keep it short, and you allow the user to reach the other point. You don't tell them, "It's a studio and core, and this page applies to blah blah blah."
There was a problem hiding this comment.
Rewritten as an index. It is now: one line on what a self-hosted deployment is and that it has every cloud feature except governance; Start here (quick start, remote server, Kubernetes, Railway with the community-maintained caveat); Where agents run (Daytona for multi-user, local runs otherwise, and that local is the only way to use your own Claude/Pi/ChatGPT subscription); Editions (OSS/EE and what EE adds); Operate a deployment (configuration, runner configuration, architecture, networking, upgrading). No product introduction, no "this page applies to" meta.
| # The provider a run gets when it does not choose. Must be one of the enabled ids. | ||
| AGENTA_RUNNER_DEFAULT_SANDBOX_PROVIDER=local | ||
|
|
||
| # --- Daytona (the AGENT RUNNER's own sandbox; NOT the code evaluator) --- |
There was a problem hiding this comment.
Why are you saying not the code evaluator?
There was a problem hiding this comment.
Because there are two Daytona configurations in the file and copying one into the other breaks agent runs. But you are right that it was said three times. It is now said once, briefly, in the Sandbox - Daytona (code evaluator) section where the bare names live: "the code evaluator's sandbox, not the agent runner (which has its own AGENTA_RUNNER_DAYTONA_* set above). It may use the same Daytona account, but not the same snapshot: this image has no agent harness installed." The runner section no longer mentions the evaluator at all.
There was a problem hiding this comment.
These examples and file are extremely verbose. It's good to have some information there, maybe sometimes about default, sometimes about what this does, but don't be verbose and write this for a developer or another agent. It's written for a human, so if it's not obvious, tell me, but if it's obvious, I don't know. A gentle on a concurrency limit is obviously the maximum concurrency runs. You can do it so that everything has a comment, but this is too verbose. The other environment variable, like your comments, are extremely verbose. Please limit them.
There was a problem hiding this comment.
Cut. The runner block in all four env examples is now roughly half the lines, and comments only carry what a human cannot infer from the name: defaults, units, secrets, and hard constraints. AGENTA_RUNNER_CONCURRENCY_LIMIT, AGENTA_RUNNER_PORT, AGENTA_RUNNER_LOG_LEVEL, and their kind have no comment at all. What survives is, for example, "Milliseconds. Must stay below AGENTA_RUNNER_DAYTONA_AUTOSTOP_MINUTES, or Daytona stops a sandbox the runner still holds", the SECRET. markers, and "45 min." on the timeouts. The long explanations live on the runner reference page, which the section header links to.
5858c34 to
07324f4
Compare
Review pass: rewritten for the readerCommit Structure and context. Every page now opens with what it is and who it is for. Assumptions and opinions, deleted. "The first question a self-hosting team asks", "this is the part teams get wrong", "keep CPU and memory generous", "a poor experience" are gone. Constraints that are real are stated as constraints (the idle TTL must stay below autostop). Not the reader's problem, deleted. The code evaluator is gone from the Daytona how-to entirely, and so is the "if the image is missing Pi" warning. The Four beats where it was missing. The store/tunnel section now gives the situation, how to tell if it applies to you, two runnable fixes (public store endpoint, or Patterns reused, not invented. Troubleshooting follows the existing docs pattern ( A real bug you caught. The sandbox resource variables were outside the runner namespace. Renamed to Env examples. The runner block in all four is roughly half the lines. Comments carry defaults, units, secrets, and hard constraints only. New page. Slugs. They exist because those three files moved (
|
Field findings from a real self-host deploymentFolded in the notes from an actual server deployment, after verifying each one against the current compose, chart, and code. Commit Documented (verified):
Dropped as stale:
Not documented (deliberate): Worth a code fix, not a doc
|
Structure pass: reorganized the self-host sidebarCommit BeforeAfterWhat changed
27 files, all under |
…mage folders Rebuild the self-host docs section around agent execution as a first-class area: new Overview, How agents run, Sandbox isolation and security, Daytona how-to, Customize the agent runtime, and a runner-and-sandbox configuration reference. Move the existing guides/infrastructure/upgrades pages into get-started, deploy-to-production, access-control, architecture, and upgrade-and-migrate groups while preserving every URL via slug frontmatter, and redirect the three deleted agent-runner guides. Reorganize the runner image folders: services/runner/docker -> images/service and services/runner/sandbox-images/daytona -> images/sandbox/daytona, updating the Railway CI workflow, the build-and-push script, the dev Compose build contexts, and the README cross-references. Add hosting/README.md mapping the deployment surfaces and the two-image model, and document the canonical AGENTA_RUNNER_* vars in the OSS and EE env examples. Make the Daytona snapshot resources configurable (AGENTA_SANDBOX_CPU/MEMORY_GB/DISK_GB, disk default lowered 8 -> 5) and align the snapshot name to the one the recipe actually builds, agenta-sandbox-pi, including the runner code default. Claude-Session: https://claude.ai/code/session_01XhENr63WL9npkKrJGnzDc1
…ale category files Delete guides/07-deploy-the-agent-runner, guides/08-custom-agent-runner-images, and guides/09-agent-daytona-sandboxes (superseded by the Agent execution pages and redirected), plus the now-empty guides/ and infrastructure/ _category_.json files. Claude-Session: https://claude.ai/code/session_01XhENr63WL9npkKrJGnzDc1
325ef16 to
07cffc7
Compare
cc577a8 to
b5b06d1
Compare
1 participant
What changed
This is the docs + hosting-layout + image-reorg slice of the runner self-hosting cleanup. Three things, one review:
1. Self-host docs restructured around agent execution
The self-host section now treats agent execution as a first-class area next to deployment and access control. New sidebar:
Every moved page keeps its URL via
slug:frontmatter, so no bookmark breaks. The three superseded agent-runner guides (deploy-the-agent-runner, custom-agent-runner-images, agent-daytona-sandboxes) are deleted and redirected to their successors indocusaurus.config.tsanddocusaurus.config.dev.ts. Touched pages get the variable-name and worker-list corrections from the cleanup (provider pair replacesAGENTA_SANDBOX_LOCAL_ALLOWED,workerStreams/workerQueuesreplace the seven per-worker names,SUPERTOKENS_EMAIL_DISABLED→AGENTA_ACCESS_EMAIL_DISABLED,with-tunnelprofile name, and so on).cd docs && pnpm buildpasses with no broken-link errors.2. Runner image folders reorganized
Two images, two clearly separated folders:
services/runner/docker/→services/runner/images/service/(the runner service image)services/runner/sandbox-images/daytona/→services/runner/images/sandbox/daytona/(the sandbox agents run in)All references updated: the Railway CI workflow, the build-and-push script, the OSS/EE dev Compose build contexts, and the README cross-references.
hosting/README.mdis added to map the deployment surfaces (Compose variants per edition/mode, Helm, Railway) and the two-image model. The canonicalAGENTA_RUNNER_*variables are documented in the OSS and EE env examples.3. Sandbox size + snapshot name fixes
Resources(cpu=2, memory=4, disk=8)is now configurable viaAGENTA_SANDBOX_CPU,AGENTA_SANDBOX_MEMORY_GB, andAGENTA_SANDBOX_DISK_GB, with the disk default lowered from 8 to 5 GB (the session working directory mounts from the store, so local disk holds the image plus temp files). The "Customize the agent runtime" how-to documents the three variables and the tradeoff. This only takes effect on a snapshot rebuild.agenta-sandbox-pi, but the runner code default wasagenta-agent-runner. Aligned everything (recipe, how-to, runner reference, and theDEFAULT_DAYTONA_SNAPSHOTcode default) toagenta-sandbox-pi, which is what the recipe actually builds and the deployed/QA snapshot.Base
Stacked on
fix/runner-env-narrowing(PR #5298) so this PR shows only its own 52-file diff. Basing onbig-agentsdirectly would include that lane's changes.https://claude.ai/code/session_01XhENr63WL9npkKrJGnzDc1