Skip to main content
Manage sandboxes For a detailed overview, please visit the sandbox’s reference page.
The cpln sandbox commands find the org’s sandbox GVC themselves, so --gvc is not needed. A GVC named by --gvc, the CPLN_GVC environment variable, or your profile is used as given.

sandbox access-report

Show the access report for the referenced sandbox Usage
Common Options Reference

sandbox audit

Retrieve audit trail events for the referenced sandbox Usage
Common Options Reference
  • Show the audit trail events of a sandbox from the last 7 days (the default)
  • Show the audit trail events of a sandbox from the last 24 hours

sandbox connect

Connect to a dev sandbox: its IDE, terminal, or SSH Refer to the dev sandbox guide for additional details. Usage
This command connects to a dev sandbox. To open a shell in a session of a worker sandbox, use sandbox session connect.
Common Options Reference
  • Open the browser IDE of a dev sandbox (the default)
  • Open the browser terminal of a dev sandbox
  • Print a one-time sign-in link instead of opening the browser, for a browser on another machine
  • Connect with VS Code over SSH (use --ide cursor for Cursor)
  • Open an SSH tunnel to the sandbox and connect from any terminal or IDE
  • Open an SSH tunnel using a preferred local port

sandbox create

Create a new sandbox Usage
--type dev, the default, creates a dev sandbox: an IDE you sign in to. --type worker creates an agent sandbox, which holds the sessions that run commands.
Common Options Reference
  • type
    • Choices: dev, worker
    • Default: dev
  • cpu
    • Type: string
    • Default: 1000m for a dev sandbox, 4000m for a worker sandbox
  • memory
    • Type: string
    • Default: 2Gi for a dev sandbox, 8Gi for a worker sandbox
  • initial-capacity
    • Type: number (GB)
    • Default: 20
    • Minimum Value: 10
    • Cannot be changed after the sandbox is created
  • app-port
    • Type: number
    • Default: 8080
    • Ports 22, 7681, 8443, 8888, 49983, and 49984 are reserved
  • scale-to-zero-delay
    • Type: number (seconds)
    • Default: 300
    • Minimum Value: 30
    • Maximum Value: 3600
  • max-sessions
    • Worker sandboxes only
    • Type: number
    • Default: 20
    • Minimum Value: 1
    • Maximum Value: 500
  • min-workers
    • Worker sandboxes only
    • Type: number
    • Default: 1
    • Minimum Value: 1
    • Maximum Value: 100
  • max-workers
    • Worker sandboxes only
    • Type: number
    • Default: 10
    • Minimum Value: 1
    • Maximum Value: 100
    • Must be at least min-workers
  • idle-delete-delay
    • Worker sandboxes only
    • Type: number (seconds)
    • Default: 3600
    • Minimum Value: 300
    • Maximum Value: 604800
  • Create a dev sandbox
  • Create a worker sandbox sized for the sessions it holds
  • Create the first worker sandbox of an identity and set how the identity’s worker sandboxes scale

sandbox delete

Delete one or more referenced sandboxes and their home volumes Usage
Deleting a sandbox also deletes its home volume, and the data on it is lost.
Common Options Reference

sandbox edit

Edit the referenced sandbox, as YAML, within an editor Usage
The default editor can be set by using the EDITOR environment variable.
Common Options Reference

sandbox eventlog

Show the event log of the referenced sandbox Usage
Common Options Reference

sandbox get

Retrieve one or more referenced sandboxes Usage
An empty reference will return all references
Common Options Reference
  • Get all sandboxes
  • Get only the worker sandboxes
  • Get one sandbox

sandbox patch

Update the referenced sandbox’s metadata using an input file Usage
Running this command with the option --file - sets the input to stdin. The input is required to be a valid JSON or YAML string (e.g., {"description": "My new description"} or description: My new description). To complete the update, press Control-D (or Control-Z if you are using Windows).
Common Options Reference

sandbox permissions

Show the grantable permissions for a sandbox object type Usage
Common Options Reference

sandbox session

Manage the sessions of a worker sandbox For a detailed overview, please visit the sandbox sessions’ reference page.
Pass --sandbox to name the worker sandbox that holds the session. Leave it out to go through the org’s sandbox GVC, where the session id alone finds its worker sandbox.

sandbox session connect

Open an interactive shell, or run a command in a terminal, in a session of a worker sandbox Usage
The shell is bash when the session’s image has it and sh otherwise. To run a single command, use sandbox session exec.
Common Options Reference

sandbox session create

Create a session on a worker sandbox, or on an identity’s worker sandboxes Usage
The session token is printed only by this command. Without --sandbox, the server appends -<worker sandbox key> to the session id, so use the id this command returns.
--set firewall... is taken only without --sandbox. The session is placed on a worker sandbox that has exactly those outbound rules, and one is added when none has room. Refer to Lock down egress per session for additional details.
Common Options Reference
  • Create a session on a worker sandbox, running a public image
  • Create a session on one of an identity’s worker sandboxes with room, adding one when none has room
  • Create a session that serves port 3000, has a 1Gi memory limit, and keeps the output of every process in its log
  • Create a session that may only reach the listed hostnames

sandbox session delete

Delete one or more sessions of a worker sandbox Usage
Common Options Reference

sandbox session exec

Run a command in a session of a worker sandbox Usage
The command’s output streams to your terminal, and its exit code becomes the exit code of the CLI.
Common Options Reference
  • Run a command in a session
  • Pipe a script into a command in a session

sandbox session get

Show one or more sessions, or with no session id, list the sessions of a worker sandbox or of the GVC Usage
Common Options Reference
  • List the sessions of a worker sandbox, ended ones included
  • List the sessions on the worker sandboxes of an identity
  • Show one session

sandbox session logs

Show the log of a session, live or ended Usage
The log always holds the lifecycle lines of the session. The output of its processes is kept only when the session was created with --log.
Common Options Reference
  • Show the log of a session
  • Keep printing new lines until the session ends
  • Show only the stderr lines that contain the given text

sandbox session metrics

Show the resource series of a session, live or ended Usage
Common Options Reference
  • Show the resource series of a session, cut to one point
  • Show the last hour of the resource series in at most 60 points

sandbox session preview

Open a session’s preview on a port in the browser Usage
A link to a token preview opens one browser once and expires shortly. A link to a public preview does not expire.
Common Options Reference
  • Open a session’s preview on port 3000 in the browser
  • Print the link instead of opening it

sandbox session processes

List the running processes of a session Usage
Common Options Reference

sandbox session signal

Send SIGTERM or SIGKILL to a process of a session Usage
Common Options Reference
  • Send SIGTERM (the default) to a process, named by its pid
  • Send SIGKILL to a process, named by the tag it was started with

sandbox start

Start one or more stopped sandboxes Usage
Common Options Reference

sandbox stop

Stop one or more sandboxes until they are started; their home volumes are kept Usage
A stopped sandbox keeps its home volume and stays stopped until sandbox start is run. Nothing wakes it in between.
Common Options Reference

sandbox tag

Manage the tags belonging to one or more referenced sandboxes Usage
Built-in tags, which begin with cpln/*, can’t be modified.
Common Options Reference
  • Add a tag
  • Update same tag (after running the example above)
  • Remove tag (after running the example above)

sandbox update

Update properties of the referenced sandbox Usage
Common Options Reference
  • The --set option allows the modification of the following sandbox properties:
    • description
      • Description of the sandbox
      • Type: string
    • tags
      • Tags (key=value) associated with the sandbox
      • Type: string
    • spec.identityLink
      • The identity the sandbox runs as
      • Type: string
    • spec.containers.<name>.image
      • The container image the sandbox runs
      • Type: string
    • spec.containers.<name>.cpu
      • The amount of cpu units available to the sandbox
      • Type: string
    • spec.containers.<name>.memory
      • The amount of memory available to the sandbox
      • Type: string
    • spec.containers.<name>.env.<name>.value
      • The environment variables to be available to the sandbox container
      • Type: string
    • spec.sandbox.appPort
      • The port the application inside the sandbox listens on
      • Default: 8080
      • Type: number
    • spec.sandbox.scaleToZeroDelay
      • Idle seconds (30 to 3600) before the sandbox scales to zero
      • Default: 300
      • Type: number
    • spec.sandbox.scaling.maxSessions
      • Worker sandboxes only: the sessions (1 to 500) one worker sandbox holds at most
      • Default: 20
      • Type: number
    • spec.sandbox.scaling.minWorkers
      • Worker sandboxes only: the worker sandboxes (1 to 100) kept for the identity
      • Default: 1
      • Type: number
    • spec.sandbox.scaling.maxWorkers
      • Worker sandboxes only: the worker sandboxes (1 to 100) the identity grows to at most
      • Default: 10
      • Type: number
    • spec.sandbox.scaling.idleDeleteDelay
      • Worker sandboxes only: seconds (300 to 604800) a worker sandbox the server added stays empty before it is deleted
      • Default: 3600
      • Type: number
  • Update a sandbox’s description
  • Set how long a sandbox stays idle before it scales to zero
  • Set the most sessions a worker sandbox holds