exec runs one command inside a running sandbox and returns its buffered output, exit code, and
truncation status in a single response. The command runs in the workload container, so it sees
your image’s filesystem and processes.
Execute a command
The response reports buffered
stdout and stderr, exactly one process outcome (an exit code,
including zero, or a timeout marker), and a truncated flag. A timeout may carry partial
output; it never carries an exit code.
Output limits
Combined stdout and stderr are capped at a server-configured limit of no more than 1 MiB;truncated reports when the cap was hit. Truncation is orthogonal to the process outcome: a
truncated response still carries the real exit code. Write large output to a file and snapshot,
rather than through stdout.
Retries and errors
Exec requires arunning sandbox and never wakes one implicitly; any other non-quarantined state
returns 409 sandbox_not_running. An optional Idempotency-Key makes a retry replay-safe instead
of double-executing.
Transport failures use stable codes and discard partial output: spawn_failed (the container
runtime failed the command instead of running it, for example a missing executable) and
sandbox_stopped (the sandbox had no running instance when the command was dispatched). Both mean
the command did not run, so both are safe to retry.
When the outcome is unknown
A command that was dispatched but whose result could not be read returns an indeterminate outcome rather than an error, alongside any output collected before the connection was lost. The CLI exits76 and prints a warning; the API returns 200 with indeterminate in place of exit.
This is deliberately not reported as a failure, because it is not one: the command may have run to
completion. Do not blindly re-run it. Check whether it already took effect, and re-run only if it
did not — or make the command safe to run twice.
The same caution applies to a timeout. A timeout stops the API waiting for your command; it does
not stop the command, which keeps running inside the sandbox.
To make a retry safe in every one of these cases, send an Idempotency-Key. A repeated request
carrying the same key replays the recorded outcome instead of executing a second time. The CLI
generates one for every hiloop sandbox exec automatically and reuses it across its own retries,
so a response lost in transit never turns into a second execution.
Interactive access
hiloop sandbox ssh <sandbox> connects to a running sandbox with stock OpenSSH. You need no SSH
key, no ssh configuration, and no separate credential: the organization-scoped API credential you
already use authorizes the connection, and hiloop supplies the key material for one session. How
the connection is authorized, and what never enters the sandbox, is covered in
shell access.
This verb needs the sandbox SSH endpoint, which an operator enables per deployment and which is off
by default. On the hosted service it is currently enabled only in pre-release environments. Where it
is off, a connect is refused with
unsupported_capability. See
what’s live today.-- is passed to ssh: options first, then an optional remote command.
scp and sftp work against any image.
Arguments follow stock ssh — any leading options, then the sandbox, then an optional remote
command — so the command also serves as the remote-shell program for tools that expect one:
ssh, pass --api-url, --context, and --api-key
before it:
rsync runs itself on both ends, so it also needs the rsync binary inside your image. The
platform default image does not carry one: use hiloop sandbox cp, or install rsync in the
sandbox first.
scp -S and sftp -S take a program path and do not split it into words, so they need a
one-line wrapper on your PATH rather than the command written inline:
hiloop sandbox cp: it needs no wrapper and nothing installed
inside the sandbox.
The sandbox must be running: any other state returns 409 sandbox_not_running. Each organization
may hold a bounded number of sessions open at once (32 by default, set per deployment); a connect
beyond it is refused with session_capacity_exhausted. Close a session you are finished with and
retry.
Where a session lands
The session runs inside your workload container, so it sees your image’s filesystem and its processes, as the image’s own user. Files you create are owned by that user, andexec and ssh
see the same filesystem.
It starts in your image’s WORKDIR when it declares one, so a shell opens where your project is.
Without a WORKDIR, it starts in the login user’s home directory, and failing that at /.
Your container is otherwise untouched: its entrypoint runs unmodified, and hiloop adds only two
read-only mounts (the endpoint binary and the SSH material) plus one lifecycle hook that starts the
endpoint. No environment variables are injected, and nothing the client sends can add any — a
session’s environment is your image’s environment.
What a session may not do
The sandbox’s SSH server refuses the following, by design. Each is a deliberate limit rather than a fault, and a client that asks for one gets an error from OpenSSH:
Host-key checking is always strict and cannot be turned off:
StrictHostKeyChecking no is rejected
by design. You will never be asked to accept an unknown host key, because the key is delivered over
the authenticated API. If a sandbox is recreated it presents a different host key, so a stale
connection attempt fails closed instead of connecting to a different machine.