Diagnose a sandbox integration

Open the exact link the CLI printed, check the code, and approve as an owner, admin or developer of the account.

• If the command was stopped while it waited, run it again. It shows the same link and code, and picks up the approval.
• Approval and delivery are separate. The browser waits for the CLI to receive and verify the credential before it shows success.
• Requests expire after 15 minutes. After expiry, start a new npx withruntime login.
• On a remote terminal, use --no-browser and open its link on your own device.
• If the CLI cannot reach Runtime, check its outbound HTTPS access. Do not paste credentials into the browser or into your agent's prompt.

Run npx withruntime whoami to check a saved connection. If it is refused, run login again. RUNTIME_API_KEY overrides the saved connection. An invalid environment key can fail even when browser login worked before. Remove an unwanted override without printing its value.

If a previous credential update was interrupted, the CLI names its lock file. Remove that file only after confirming no Runtime command is running, then retry. The CLI never steals an active lock automatically.

From SDK version 0.4.0, the CLI and both SDKs use the proxy your environment names, the way curl does:

• HTTPS_PROXY carries every call to the HTTPS API and terminal WebSockets, through a CONNECT tunnel. A user:password@ in its address is sent to the proxy. HTTP_PROXY is used only for http:// addresses, never for HTTPS.
• NO_PROXY lists hosts to reach directly, split by commas or spaces. A name covers its subdomains, a leading dot is allowed, host:port limits it to one port, and * alone means every host.
• Each name works in upper or lower case. When both are set, lower case wins. A proxy address without a scheme is taken as http://.
• A proxy address that cannot be used fails immediately with invalid_proxy, naming the variable.

When the proxy cannot be reached, the error names it. For example: No answer from Runtime at https://api.withruntime.com through the proxy http://proxy:3128 (HTTPS_PROXY). If the proxy returned 407, the hint says to put credentials in the variable as http://user:password@host:port. If only HTTP_PROXY is set, the hint says to set HTTPS_PROXY, since the API is HTTPS.

On earlier versions, every call fails with connection_error ("No answer from Runtime at https://api.withruntime.com") while curl through the same proxy works, because the client connects directly:

• CLI and JavaScript SDK on Node 22.21 or later, or Node 24. Also set NODE_USE_ENV_PROXY=1. Then Node's own fetch reads those variables. Node's documentation marks this setting as still in active development.
• Under Bun, the proxy variables already work.
• The Python SDK connects directly, and no setting changes that. Upgrade.

TerminalNODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://proxy.example.com:3128 npx withruntime whoami

Node could not read an OpenSSL configuration file, so it stopped before the CLI started. This happens with a Node build that uses the system's OpenSSL, such as Homebrew's or a Linux distribution's. It also happens inside a sandbox that blocks reading outside the project, such as a coding agent's. OPENSSL_CONF naming a file that cannot be read does the same. The message names the file:

textnode: OpenSSL configuration error:...:BIO_new_file:Permission denied:...calling fopen(/opt/homebrew/etc/openssl@3/openssl.cnf, rb)

The CLI does not need that file. Give Node an empty one for the command, or let the sandbox read the file that the message names:

TerminalOPENSSL_CONF=/dev/null npx withruntime whoami

Node from nodejs.org reads no such file, so it starts either way.

no_credit_running_limit is temporary. It returns 429 with Retry-After: 5. A slot frees when any sandbox without credit stops or pauses.

• Retry with the same idempotency key, a growing delay and a bounded deadline, or stop or pause one of the sandboxes details names.
• A fork asking for more running copies than an account without credit allows never fits. Ask for fewer.
• An SDK create waits for a slot by itself, for up to two minutes by default (waitForCapacityMs in JavaScript, wait_for_capacity in Python, Ruby), and then returns the refusal. A wake and a restart wait the same way for room on their own server. A fork never waits. The error's retryable is true, for a loop of your own.
• Once the account holds prepaid credit, it runs more sandboxes immediately, with nothing to change.

Once the free usage is used up, an account with prepaid credit keeps running on that credit, with nothing to change. An account with neither is refused with included_usage_used_up until the 1st (UTC). See how much is left with npx withruntime usage, or with GET /v1/usage or GET /v1/limits. trial.availableMs is what a new sandbox without credit can still use, in milliseconds, after what running sandboxes hold; a create is refused exactly when it is 0. allowances shows what each pool has left this month. When the account has no free machine time at all, freeUsageHold says why, and the refusal's details.reason names the same rule. See free usage.

The SDKs and npx withruntime sandboxes create wait for running for you. Over raw HTTP, send Prefer: wait=60, or read the sandbox with ?waitFor=running.

Wait for running before you issue commands. A command on a sandbox that is still starting waits up to 30 seconds, then returns sandbox_not_ready. If the sandbox stops before it is ready, its stopReason says why. Report that failure with its sandbox id and request id. Do not start a new sandbox repeatedly without checking the first request's outcome.

Read its stopReason. A sandbox paused at the end of its time limit, or by :pause, has lost nothing and has no stopReason: wake it. A paused sandbox that reads pause_failed lost its memory and kept its files.

Only a person can raise a spending limit, on the account's keys page: the member who made the key, or an owner or admin. Do not create replacements in a loop; the limit counts the last 24 hours.

Each code below means nothing ran. A retry with the same idempotency key runs the call at most once. The SDKs retry each of them.

A slow disk returns an error within seconds. When the sandbox's server cannot finish writing to its disk, a new command returns sandbox_unreachable (503) after 5 seconds, with details.reason set to disk_stalled. The request ran nothing. Commands already running continue, and their output can be read as usual. Retry with the same idempotency key; the SDKs do.

A sandbox that stops responding says so. Within about 5 seconds, GET /v1/sandboxes/{id} returns unreachable with since and reason (agent_not_answering, disk_stalled or host_quarantined), and the event sandbox.unreachable is sent to your webhooks. sandbox.reachable follows when it responds again. For agent_not_answering or host_quarantined, restart the sandbox: it reboots from its disk and keeps its files.

A sandbox at its memory limit stays reachable. When the sandbox's programs fill its memory, Linux's out-of-memory killer ends one of them, never Runtime's agent. Commands keep running. Each process killed is recorded as the event sandbox.oom_kill, which names the process, its process ID and the memory it used. The event appears on the sandbox's page in the console and in GET /v1/events?resourceId=<id>, and is sent to your webhooks. A command whose own processes were killed also returns outOfMemory in its result. Give the sandbox more memory (memoryMiB), or make the program use less.

A missing response is not proof that a command failed to run. Use the same idempotency key and identical input. The server returns the first result again instead of running it twice. The SDKs do this for you. If a command's outcome is still unknown, inspect its files and processes before repeating a side effect.

A 5xx whose message says the fault is ours was reported to us when it happened, with its requestId. API errors and retries describes the full contract.

time_limit_too_short (409) means the command could outlast the sandbox's time. A command is refused, and nothing runs, when the timeout you set is longer than the time left before the sandbox's time limit, or before the end of its funding once credit, free usage or a spending limit ran out. A paused sandbox is refused before it is woken, so the wake costs nothing. For a time limit, raise it first (runtime sandboxes extend <id> 600, sbx.extend(600)). For funding, add credit or raise the limit (runtime limits). Or give the command a shorter timeout. details.secondsLeft gives the time left. A sandbox with no time limit and credit to run accepts a command of up to 24 hours. A command with no timeout of yours is not refused: it runs until the sandbox's end, unless that is within about three seconds.

At create or resize, time_limit_too_short means the time limit is too short to load the sandbox's memory back after a pause. The message names the least timeoutSeconds for that size (190 for 65,536 MiB). Use it, leave the limit out, or ask for less memory.

Check the command's exit code, standard error and truncation flags. HTTP success means the operation was handled, not that the program returned zero.

• A result holds at most 64 KiB of each stream for a command up to 60 seconds. stdoutTruncated or stderrTruncated is true when the rest was dropped. Stream the output, or write it to a file and read that.
• Use check: true (check=True in Python) to raise on a non-zero exit.
• A timeout is a result with timedOut: true. Raise timeoutMs, or run long jobs in the background and follow their output.

File errors name the path and the reason: file_not_found, is_a_directory, not_a_directory, permission_denied. Paths are absolute. /workspace is home. Outside your own files, use sudo in a command.

The sandbox's disk is full. Commands still run on a full disk, so you can free space with a command, such as rm -rf /workspace/node_modules/.cache, or du -sh /workspace/* | sort -h to find what is large. A disk cannot be grown in place. For more room, create a sandbox with a larger diskMiB.

Check the sandbox's network rules and the destination port.

• npx withruntime sandboxes network <id> shows the rules.
• A sandbox without credit reaches ports 80 and 443 only. A paid sandbox of an account with a kept top-up reaches every port. openPorts in the rules says which. See the sandbox environment.
• Name lookups or pip install time out in a sandbox from your own image on a Debian or Ubuntu base, such as python:3.12-slim, built before 30 September 2026. The image kept its own /etc/resolv.conf. Build it again. Every image built since uses Runtime's resolver (images).
• API rate limit exceeded for <address> from api.github.com: calls without a token share a limit with everyone on that address. Store a GitHub token as a secret (shared addresses and per-address limits).
• Do not disable security protections to make a migration appear successful.

Read the sandbox's sandbox.secret_not_applied event first. Runtime sends it when it sees a placeholder go out without being replaced. Its reason and message say why (events): npx withruntime events --type sandbox.secret_not_applied. With no event, check these four things, in order. They decide whether a request carries a secret.

1. The host. npx withruntime secrets ls shows each secret's hosts. The URL's host must be one of them by name: *.example.com covers api.example.com but not example.com, and an IP address never matches.
2. The request. Only HTTPS carries a secret, and only in its credential header, never in the URL or the body. With rules, the method and path must match a rule: /ingest does not match /ingest/, and a path that could be read two ways (an encoded slash, a semicolon or a backslash) gets no secret that has rules.
3. The route. Inside the sandbox, run curl -sv https://<host>/ -o /dev/null 2>&1 | grep -i issuer. For a secret's host, the issuer is Runtime's egress certificate. The server's own issuer means the request never reached the step that adds the secret. The client went around the sandbox's proxy (raw sockets and some HTTP libraries ignore HTTPS_PROXY), or the host is in its NO_PROXY. The sandbox's own NO_PROXY lists only loopback and private addresses, so a secret's host is there only if your code added it. If the server could not add the secret at that moment, a withheld event says so. That is Runtime's fault, not your code's.
4. Pinned certificates. A client with its own certificate list needs /usr/local/share/ca-certificates/runtime-egress.crt added to it.

If all four hold and the placeholder still arrives, write to support with the sandbox's id, the time of the request and the output of step 3.

Compare like with like. Compare total CPU-seconds, provisioned memory, the quoted CPU floor and actual running duration. Include startup, dependency installation, retries and cleanup. A running sandbox's charges settle as it runs, so wait for it to stop before comparing the total.

• Usage & billing groups daily and monthly settled service charges in UTC. Its estimate for the rest of the month is the pace so far, not a charge.
• A payment adds credit. It is not service usage.
• Paused storage is a separate meter, so stopping compute does not prove all retained-storage charges have ended.

Check pausedExpiresAt, available credit and the error code. Wake needs room on the original host for CPU, memory, the full disk allowance and its next snapshot. A full host can refuse restoration while preserving the saved state. When the host is short only because of work Runtime runs at the lowest priority there (such as Runtime's own CI), the wake pauses that work and waits up to 20 seconds for the room before it returns no_capacity. A request that would wake a sandbox while a snapshot of it is being taken waits for the snapshot to finish, then wakes it. Past the request's own deadline, it returns snapshot_capturing (409). A retry once the snapshot is over wakes it.

• Do not delete it as a retry step.
• Missing memory images are an error, not an instruction to claim a fresh boot restored the previous process.
• Keep important outputs outside a sandbox before relying on long retention.

See storage and retention terms and isolation.

A wake that is still resuming after a minute is stuck on our side. A wake that boots from the disk, because the memory could not be kept (memoryRestored: false), does so within seconds. While a sandbox is resuming, a command on it waits up to 30 seconds and then returns sandbox_not_ready.

An operation we cannot finish gives up within about a minute. The sandbox then stays in the state it was moving from (starting, resuming, pausing or stopping), with its files kept and nothing charged. Its response carries operationFailed: the action (start, wake, pause, stop or delete) and when it failed. Every command and wake on it returns operation_failed (500) immediately instead of waiting. Our operators are alerted. Retrying the same call does not help. A stop or a delete does. A wake or pause that gave up because its machine held the sandbox for our operators is retried every five minutes. Once the machine has let it go, the sandbox is paused again (with stopReason: "pause_failed" and memoryRestored: false on its next wake if its memory could not be kept), and its next command wakes it.

• Your other sandboxes are not affected: a stuck operation holds one sandbox.
• Do not delete the stuck sandbox as a retry step, and do not retry commands on it in a loop. Its files are kept while it is stuck.
• After operation_failed, stop it (runtime sandboxes stop <id>) to keep its disk, then restart it, or delete it if you do not need its files. A sandbox whose stop or delete gave up can only be deleted. Write to support to keep its disk.
• After wake_refused, retry the same wake or restart in a few minutes. It is safe to repeat, and nothing was queued. Its paused storage is not billed from the first refused wake until it can wake. Write to support if it still fails after an hour.
• Continue in a new sandbox from the same image if the work cannot wait.
• Write to support with the sandbox id and the time it got stuck. An operator clears it and tells you whether its files can be brought back.

Stop is asynchronous. The SDKs wait for stopped. Over HTTP, send Prefer: wait=60, or read the sandbox with ?waitFor=stopped. Compute ends after confirmed VM shutdown. Do not report cleanup complete just because the request was accepted.

MCP tools and a framework's built-in shell are different paths. Configure the framework's execution backend, or replace its tool registration explicitly. Run a probe that prints the sandbox id and verifies a remote file round trip before you call the switch complete.