# sandscale workspace

> sandscale workspace: Cloud workspaces. Usage, options and examples, generated from the CLI.

Cloud workspaces.

[All commands](https://sandscale.dev/docs/reference/cli)

Uses your own Sandscale sign-in (sandscale login). Sharing a workspace and its credentials stay in the console. Not here: config-ssh (use sandscale workspace ssh or port-forward).

| Command | What it does |
| --- | --- |
| `list` | Your workspaces |
| `show` | One workspace |
| `create` | Create a workspace from a template |
| `open` | Start it when stopped, wait until it runs, then ssh (or a terminal); with --ide, open it in an editor |
| `ssh` | The system ssh through Sandscale, with a short-lived certificate and a checked host key |
| `logs` | The workspace agent's or a build's logs |
| `stop` | Stop a workspace |
| `restart` | Stop it, wait until it stopped, then start it |
| `update` | Rebuild it on its template's active version |
| `rename` | Rename a workspace (your own sign-in) |
| `delete` | Delete a workspace and its disks (your own sign-in; Sandscale may ask you to confirm it is you) |
| `port-forward` | Forward local ports to a workspace's ports (until Ctrl+C) |
| `schedule` | Show or set when it starts, stops after a start, and stops when idle |
| `templates` | Templates you may create workspaces from |
| `dotfiles` | Your dotfiles repository, applied to workspaces (your own sign-in) |
| `ping` | Round trips to Sandscale and the state of the workspace agent |
| `stat` | CPU, memory and disk the workspace agent last reported |
| `support-bundle` | A JSON file for support: the workspace, its agent, builds and logs, with tokens and secrets removed |
| `ssh-cert` | Make sure the workspace key and a fresh SSH certificate are on disk |
| `ssh-proxy` | ssh's ProxyCommand: for tools that run their own ssh |

## `sandscale workspace list`

Your workspaces.

```
sandscale workspace list: Your workspaces

Usage:
  sandscale workspace list [--project ID] [--limit N] [--cursor C] [--json]

Examples:
  sandscale workspace list
  sandscale workspace list --json
```

## `sandscale workspace show`

One workspace.

```
sandscale workspace show: One workspace

Usage:
  sandscale workspace show NAME|ID [--json]

Examples:
  sandscale workspace show payments-dev
```

## `sandscale workspace create`

Create a workspace from a template.

```
sandscale workspace create: Create a workspace from a template

Usage:
  sandscale workspace create NAME --template ID [--template-version ID] [--param KEY=VALUE]... [--ttl 8h] [--json]

Examples:
  sandscale workspace create payments-dev --template go-service --param region=eu1
```

## `sandscale workspace open`

Start it when stopped, wait until it runs, then ssh (or a terminal); with --ide, open it in an editor.

```
sandscale workspace open: Start it when stopped, wait until it runs, then ssh (or a terminal); with --ide, open it in an editor

Usage:
  sandscale workspace open NAME|ID [--terminal] [--no-connect] [--json]
  sandscale workspace open NAME|ID --ide browser [--start] [--json]

Start it when stopped, wait until it runs, then ssh (or a terminal). --ide browser opens it in the browser; editors that connect over SSH use sandscale workspace ssh.

Examples:
  sandscale workspace open payments-dev
  sandscale workspace open payments-dev --terminal
  sandscale workspace open payments-dev --ide vscode --start
```

## `sandscale workspace ssh`

The system ssh through Sandscale, with a short-lived certificate and a checked host key.

```
sandscale workspace ssh: The system ssh through Sandscale, with a short-lived certificate and a checked host key

Usage:
  sandscale workspace ssh NAME|ID [--user USER] [--ssh-arg ARG]... [-- COMMAND [ARG...]]

ssh uses a key made once for this workspace (in ~/.sandscale/ssh/<id>/) and a certificate Sandscale signs for it, valid for 10 minutes and renewed when less than 2 minutes remain. The workspace's host key is checked against Sandscale's host CA, or the key its agent registered; host key checking is never turned off. Everything after -- is the command the workspace runs (ssh joins its words with spaces, as ssh does). Options for ssh itself go in --ssh-arg, one word each. Forwarding ports: workspace port-forward.

Examples:
  sandscale workspace ssh payments-dev
  sandscale workspace ssh payments-dev -- ls -la /srv
  sandscale workspace ssh payments-dev --ssh-arg=-A -- git pull
```

## `sandscale workspace logs`

The workspace agent's or a build's logs.

```
sandscale workspace logs: The workspace agent's or a build's logs

Usage:
  sandscale workspace logs NAME|ID [--build ID|latest] [--follow] [--after N] [--limit N] [--json]

Examples:
  sandscale workspace logs payments-dev --follow
  sandscale workspace logs payments-dev --build latest
```

## `sandscale workspace stop`

Stop a workspace.

```
sandscale workspace stop: Stop a workspace

Usage:
  sandscale workspace stop NAME|ID [--json]

Examples:
  sandscale workspace stop payments-dev
```

## `sandscale workspace restart`

Stop it, wait until it stopped, then start it.

```
sandscale workspace restart: Stop it, wait until it stopped, then start it

Usage:
  sandscale workspace restart NAME|ID [--json]

Examples:
  sandscale workspace restart payments-dev
```

## `sandscale workspace update`

Rebuild it on its template's active version.

```
sandscale workspace update: Rebuild it on its template's active version

Usage:
  sandscale workspace update NAME|ID [--param KEY=VALUE]... [--json]

Changes nothing when it already runs the active version (unless --param is given).

Examples:
  sandscale workspace update payments-dev
```

## `sandscale workspace rename`

Rename a workspace (your own sign-in).

```
sandscale workspace rename: Rename a workspace (your own sign-in)

Usage:
  sandscale workspace rename NAME|ID NEW-NAME [--json]

Examples:
  sandscale workspace rename payments-dev payments-old
```

## `sandscale workspace delete`

Delete a workspace and its disks (your own sign-in; Sandscale may ask you to confirm it is you).

```
sandscale workspace delete: Delete a workspace and its disks (your own sign-in; Sandscale may ask you to confirm it is you)

Usage:
  sandscale workspace delete NAME|ID [--yes] [--json]

You type the workspace's name to confirm, or pass --yes. When Sandscale asks you to confirm it is you, the CLI asks at this terminal (authenticator code, emailed code, or your passkey in the console); without a terminal nothing is asked, nothing is deleted, and the exit code is 4.

Examples:
  sandscale workspace delete payments-old
```

## `sandscale workspace port-forward`

Forward local ports to a workspace's ports (until Ctrl+C).

```
sandscale workspace port-forward: Forward local ports to a workspace's ports (until Ctrl+C)

Usage:
  sandscale workspace port-forward NAME|ID LOCAL:REMOTE... [--bind ADDRESS] [--user USER]
  sandscale workspace port-forward NAME|ID --tcp [127.0.0.1:]LOCAL:REMOTE... [--user USER]

Each LOCAL:REMOTE (or one port for both) listens on this computer and reaches that port on the workspace, through ssh. It listens on 127.0.0.1 only; --bind 0.0.0.0 (or another address, or *) makes it reachable from your network and prints a warning. --tcp takes a loopback address only. At most 32 forwards.

Examples:
  sandscale workspace port-forward payments-dev 8080:80
  sandscale workspace port-forward payments-dev 3000 5432:5432
  sandscale workspace port-forward payments-dev --tcp 8080:3000
```

## `sandscale workspace schedule`

Show or set when it starts, stops after a start, and stops when idle.

```
sandscale workspace schedule: Show or set when it starts, stops after a start, and stops when idle

Usage:
  sandscale workspace schedule show NAME|ID [--json]
  sandscale workspace schedule start NAME|ID "CRON"|off [--timezone ZONE] [--json]
  sandscale workspace schedule stop NAME|ID DURATION|off [--json]
  sandscale workspace schedule idle NAME|ID DURATION|default [--json]

CRON has 5 fields (minute hour day month weekday); the time zone defaults to this machine's. Setting needs your own sign-in; your organization's policy can shorten what you set (show prints the effective values).

Examples:
  sandscale workspace schedule show payments-dev
  sandscale workspace schedule start payments-dev "30 8 * * 1-5" --timezone Europe/Berlin
  sandscale workspace schedule stop payments-dev 8h
```

## `sandscale workspace templates`

Templates you may create workspaces from.

```
sandscale workspace templates: Templates you may create workspaces from

Usage:
  sandscale workspace templates list [--json]
  sandscale workspace templates show NAME|ID [--json]

Examples:
  sandscale workspace templates list
  sandscale workspace templates show go-service
```

## `sandscale workspace dotfiles`

Your dotfiles repository, applied to workspaces (your own sign-in).

```
sandscale workspace dotfiles: Your dotfiles repository, applied to workspaces (your own sign-in)

Usage:
  sandscale workspace dotfiles show [--json]
  sandscale workspace dotfiles set URL [--branch B] [--install-script PATH] [--target-path PATH] [--auto-sync] [--json]
  sandscale workspace dotfiles remove [--json]
  sandscale workspace dotfiles sync NAME|ID [--json]

URL is https://, ssh:// or git@host:path, with no user name, password or token in it.

Examples:
  sandscale workspace dotfiles set https://github.com/me/dotfiles
  sandscale workspace dotfiles sync payments-dev
```

## `sandscale workspace ping`

Round trips to Sandscale and the state of the workspace agent.

```
sandscale workspace ping: Round trips to Sandscale and the state of the workspace agent

Usage:
  sandscale workspace ping NAME|ID [--count N] [--json]

Examples:
  sandscale workspace ping payments-dev --count 5
```

## `sandscale workspace stat`

CPU, memory and disk the workspace agent last reported.

```
sandscale workspace stat: CPU, memory and disk the workspace agent last reported

Usage:
  sandscale workspace stat NAME|ID [--json]

Examples:
  sandscale workspace stat payments-dev
```

## `sandscale workspace support-bundle`

A JSON file for support: the workspace, its agent, builds and logs, with tokens and secrets removed.

```
sandscale workspace support-bundle: A JSON file for support: the workspace, its agent, builds and logs, with tokens and secrets removed

Usage:
  sandscale workspace support-bundle NAME|ID [--output FILE|-] [--logs N]

Written with mode 0600 and never over an existing file. Review it before you share it: names, ids and log lines are kept.

Examples:
  sandscale workspace support-bundle payments-dev
```

## `sandscale workspace ssh-cert`

Make sure the workspace key and a fresh SSH certificate are on disk.

```
sandscale workspace ssh-cert: Make sure the workspace key and a fresh SSH certificate are on disk

Usage:
  sandscale workspace ssh-cert NAME|ID [--json]

Prints nothing when it is run by ssh (or its output is not a terminal); at a terminal it says who the certificate is for and until when. ssh reads its key files before it runs the ProxyCommand, so config-ssh has ssh run this first (a `Match exec` line in each host's entry); you can also run it before starting another tool that reads ~/.sandscale/ssh/<id>/id_ed25519 and id_ed25519-cert.pub.

Examples:
  sandscale workspace ssh-cert payments-dev
  sandscale workspace ssh-cert payments-dev --json
```

## `sandscale workspace ssh-proxy`

ssh's ProxyCommand: for tools that run their own ssh.

```
sandscale workspace ssh-proxy: ssh's ProxyCommand: for tools that run their own ssh

Usage:
  sandscale workspace ssh-proxy NAME|ID

Keeps a valid certificate for the workspace in ~/.sandscale/ssh/<id>/ (made once, renewed when less than 2 minutes remain), then carries the SSH bytes over Sandscale on stdin and stdout. Use it as `ProxyCommand sandscale workspace ssh-proxy NAME` with `IdentityFile ~/.sandscale/ssh/<id>/id_ed25519` and `CertificateFile ~/.sandscale/ssh/<id>/id_ed25519-cert.pub`; config-ssh writes all of that for you. A refusal is printed on stderr, with the exit codes below.

Examples:
  sandscale workspace config-ssh
```

## Examples

```
sandscale workspace list
sandscale workspace open payments-dev
sandscale workspace ssh payments-dev -- make test
```

Exit codes: 0 done, 1 failed, 2 usage, 3 no session, 4 refused, 5 not found, 6 conflict or precondition, 7 rate limited.

This page is generated from the sandscale CLI's command registry. Do not edit it by hand.

---
Source: https://sandscale.dev/docs/reference/cli/workspace
