Sandbox issues

When the sandbox itself isn't behaving — won't start, won't stay up, file ops fail.

Sandbox creation hangs or times out

The agent calls sandbox_create, then waits forever (or times out).

Common causes:

• Server is disconnected. Check the dashboard at app.agentry.run/clusters. If the server shows red / disconnected, see Connection + tunnel.
• Server is out of disk. The runtime image needs ~500MB; each sandbox adds 200MB-1GB. SSH to your server and check df -h. Free space if needed and retry.
• Runtime image pull is slow. First sandbox after the runtime image updates pulls a fresh layer (~100-200MB). 60-120 seconds is normal on a slow connection.

Recovery: if the create succeeded but the agent's connection timed out, the sandbox might be running. Check:

agentry sandbox ls

If it's there in Running state, tell the agent the sandbox id and continue.

Name collisions

The agent says it created ecommerce-store, but sandbox_create returned ecommerce-store-7f2a. The agent then tries to call command_run with sandbox_id: ecommerce-store and gets "sandbox not found".

Cause: there's already a sandbox named ecommerce-store on the server (from a previous chat). agentry auto-suffixed the new one to avoid overwriting the old.

Fix: tell the agent to use the suffixed id:

Use the actual sandbox_id from the create response: ecommerce-store-7f2a. Update any tool calls that reference the wrong name.

A well-behaved agent reads the response and uses the right id. A confused agent needs the nudge.

"sandbox not found"

Error: sandbox "pebble-app-7f2a" not found

Causes:

• Typo in the id. Compare to agentry sandbox ls.
• The sandbox was deleted (by you, by the reaper, or by a TTL expiry).
• You're targeting the wrong server. Check with agentry server current.

If it was reaped, check the deployment side — deploys outlive sandboxes. Your code might still be running there.

Files written, but they're not where I expect

Inside a sandbox, files live under /workspace. The conventional project root for an app the AI is building is /workspace/projects/<project-name>/.

If the agent wrote to /tmp or /home, work isn't lost — it's just not where agentry expects it for deploy. A sandbox holds one project, and the deploy looks for it under /workspace. Ask the agent to move the work there:

Move the project into /workspace/projects/app so it deploys cleanly.

"permission denied" writing files

EACCES: permission denied, open '/workspace/projects/...'

Cause: the runtime user doesn't own that path. Usually means the agent created a directory as root and switched users, or you're trying to write to a path that's mounted read-only.

Fix:

agent: command_run "chmod -R u+w /workspace/projects/<name>"

If it's a mount issue (writing to /etc/sandbox/creds, which is read-only by design), don't fight it — that's the credential mount and shouldn't be written.

Sandbox is up but URL returns 404

The runtime is healthy but https://<sandbox>.agentry.live returns 404.

Causes:

1. The dev server isn't running. A sandbox without a process listening on a port shows the default 404 page. Have the agent run project_list — if nothing shows as running, start it (project_start ...).
2. The dev server is listening on the wrong port. agentry routes to the first port the runtime sees in use. If your app uses port 5173 but agentry expects 3000, the agent should call port_wait for the right port — the routing follows.
3. The route table hasn't synced yet. the bridge route sync happens every 10 seconds. If you just shared a port, give it a moment.

Sandbox CPU/memory pressure

Some apps (large Next.js builds, ML inference) push past the sandbox's default resource limits.

Symptoms:

• OOMKilled in logs.
• npm run build hangs and then exits with "JavaScript heap out of memory".
• Dev server gets SIGKILL'd mid-request.

Fix:

• For Node memory issues: increase Node's heap. NODE_OPTIONS=--max-old-space-size=4096 npm run build.
• For genuine compute pressure: bump the sandbox's resource limits when creating. See the resources field in sandbox_create — pass higher CPU / memory caps.
• Or move to a bigger server.

Sandbox port is "already in use"

Error: listen EADDRINUSE: address already in use :::3000

Cause: another process in the sandbox is already on that port. Common after a dev server crashed without releasing the port.

Fix:

agent: command_run "pkill -f 'next dev' || true"
agent: project_start ...

Or just kill all node processes in the sandbox:

agent: command_run "pkill -f node || true; sleep 1; pkill -9 -f node || true"

Sandbox env doesn't match what I set

You set MONGODB_URL=mongodb://prod... but the agent's code reads mongodb://dev....

Causes:

• The env var was set on the sandbox via agentry env set but the running processes started before. New env reaches only new processes.

Fix: restart the projects in the sandbox.

agent: project_stop <name>
agent: project_start <name> --cmd "npm run dev"

Reaper deleted my sandbox

If you set a TTL on a sandbox via ttl_seconds, the reaper deletes it when it expires. You'll see it disappear from sandbox list.

If this was unintentional, recreate without a TTL:

Create a fresh sandbox. Don't set ttl_seconds this time.

Deployments derived from the reaped sandbox keep running — the deploy doesn't depend on the source sandbox being alive.

When all else fails

Delete the sandbox and start over:

agentry sandbox rm <id>

Then re-prompt the agent. Most agents can re-scaffold a project from a recent conversation pretty fast.

If you've made significant work in the sandbox that you don't want to lose, copy it out first:

agent: command_run "tar czf /tmp/backup.tar.gz /workspace/projects"
agent: file_read /tmp/backup.tar.gz  # then save the bytes locally

Next

• Connection + tunnel — when the server itself can't reach agentry.
• Build failures — when a build fails.
• Deploy issues — when the production side is the problem.