Skip to main content
A persistent, exposed sandbox is a Linux workspace that stays running. Your files, installed packages, processes, and local databases remain there between visits. Turn the capabilities on at creation — persistence with --persistent and a published hostname with --expose — and you get:
  • A stable <name>-box.run.cloud URL for your app
  • SSH access without exposing a public SSH port
  • VS Code Remote SSH
  • File transfer with scp
  • Optional custom domains with managed HTTPS
Earlier releases called this combination a “box” with its own runcloud box command group. Those commands still work as deprecated aliases — see the CLI reference for the mapping.

​
Create a persistent, exposed sandbox

With --expose, the CLI creates a non-pausing sandbox with 2 CPU and 24 GiB of memory, then attaches its hostname:
Override either allocation directly when a different shape is needed:
Start your web process inside the sandbox on the exposed port, such as 3000. To publish a hostname on a sandbox you already have, expose it after the fact (it must have been created with --persistent or --idle-pause 0):
The exposure response includes the stable URL:
Hostname names are lowercase DNS labels. A sandbox can have one active hostname.

​
Coding-agent image

Use runcloud/box-agent when you want Claude Code and Codex preinstalled:
Connect over SSH and start either CLI in /workspace:
The image contains no provider credentials. Authenticate with Anthropic or OpenAI after connecting. Use the regular runcloud/box image when you want the same persistent development environment without preinstalled coding agents.

​
SSH

The first setup generates a dedicated key, installs its public half in the sandbox, and adds a managed host entry to ~/.ssh/config:
You can also skip the second command:
Run Cloud carries SSH over an authenticated connection. You do not need to open port 22, manage an IP allowlist, or keep a long-lived access token in the SSH config.

​
VS Code Remote SSH

Install Microsoft’s Remote - SSH extension, then run:
The CLI creates the same SSH configuration used by the terminal and opens /workspace in VS Code. You can also choose runcloud-my-project from Remote-SSH: Connect to Host.

​
Copy files

Prefix the path inside the sandbox with :. Upload a file:
Download it again:
Copy a directory recursively:
Because setup uses standard SSH configuration, existing tools such as scp, rsync, SFTP clients, and Git-over-SSH can use the runcloud-my-project host too.

​
Custom domains

Attach a hostname you control:
The response tells you which CNAME (or flattened ALIAS at an apex) and any verification records to add at your DNS provider. Once DNS is in place, check certificate status:
Traffic moves to your sandbox when both status and sslStatus are active. HTTPS certificates are issued and renewed automatically. Remove a domain without deleting the sandbox:

​
Change the public port

The hostname stays the same while traffic moves to the new port.

​
List and inspect

Exposed sandboxes show their hostname in the regular listing:
If route activation was interrupted, retry it without replacing the hostname:

​
Delete

Destroying an exposed sandbox removes its public hostname and the sandbox together.