Shako From the Terminal

Every command of the shako CLI, with all its parameters and examples. Each VM is also a plain SSH host: ssh, scp, sftp and port forwarding work as on any server.

Quick Start

shako login
Connect this computer to your account.
shako vm create web1 --agent claude
Create a VM with Claude Code.
ssh web1.maya.shako.dev
Log in, as to any server.
shako port public web1 3000
Share port 3000 at a public address.

Get Started

You need a Shako account. shako login connects this computer to it and sets up plain SSH to your VMs.

shako login

Usage

shako login [flags]

Parameters

--no-browser: Only print the link (open it on this computer).
--name <name>: The name of this device's key (default: asked on the terminal, the host name is the default answer).

Examples

shako login

Give this computer's key a name.

shako login --name work-laptop

Only print the link, and open it in a browser on this computer.

shako login --no-browser

shako whoami

Your tenant and the VM sizes.

Usage

shako whoami

Examples

Your account name, the form of your SSH names and app URLs, and the sizes with their prices.

shako whoami

Your account, then the key that this computer signs with.

shako whoami && shako config show

shako version

The CLI's version.

Usage

shako version

Examples

The version of the CLI on this computer.

shako version

Only the version number, for a script.

shako version | cut -d' ' -f2

VMs

Create, copy, resize and delete VMs. By default, a VM sleeps when it is quiet and wakes on the next SSH login or request.

shako vm create

Create and boot a VM.

Usage

shako vm create <name> [flags]

Parameters

<name>: The new VM's name: a-z, 0-9 and single hyphens, starting with a letter, at most 31 characters. It is in the VM's SSH name and in the URLs of its public ports.
--size <size>: The size: micro 1cpu/1G/10G disk, small 1cpu/2G/20G disk, mid 2cpu/4G/40G disk, large 4cpu/8G/80G disk (default micro).
--cpus <cpus>: Custom vCPUs: 1 or an even number. It replaces the vCPUs of the size.
--memory <memory>: Custom memory, for example 3G or 1536M. The disk is 10 GB per GB of memory. It replaces the memory of the size.
--image <image>: Image release, e.g. 2026.10.27.1 (default: the current release).
--sleep <sleep>: When the VM sleeps. idle: when it is quiet; manual: only on request; never: it is always on, and restarts after a reboot or a crash (default idle).
--idle <idle>: The quiet time before the VM sleeps, for example 15m or 2h (default 15m).
--no-wait: Return before the guest's SSH is up.
--agent <agent>: A coding agent to put in the VM: claude, codex, opencode, pi, openclaw, hermes. Give several with commas (--agent claude,codex) or with one --agent for each.
--desktop: Browser use and computer use for the agents: a screen and a shared browser. Needs an agent and 4 GB of memory or more (size mid or bigger).

Examples

Create a VM of the default size, Micro.

shako vm create web1

A VM with Claude Code and Codex, and a screen and a shared browser for them. These need size Mid or bigger.

shako vm create agents --size mid --agent claude,codex --desktop

A custom size that never sleeps.

shako vm create db --cpus 2 --memory 3G --sleep never

shako vm ls

List your VMs.

Usage

shako vm ls

Examples

List your VMs: state, size, disk, sleep policy, last activity and agents.

shako vm ls

Only the VMs that are awake.

shako vm ls | grep awake

shako vm info

Show one VM.

Usage

shako vm info <vm>

Parameters

<vm>: The VM's name, from shako vm ls.

Examples

Show one VM: size, SSH name, agents, sleep policy, snapshot, usage and its last events.

shako vm info web1

Two VMs' details, one after the other.

shako vm info web1 && shako vm info api

shako vm sleep

Put a VM to sleep now.

Usage

shako vm sleep <vm>

Parameters

<vm>: The VM's name, from shako vm ls.

Examples

Put a VM to sleep now. Its programs stay in memory, saved on disk.

shako vm sleep web1

Put two VMs to sleep.

shako vm sleep web1 && shako vm sleep api

shako vm wake

Wake a VM.

Usage

shako vm wake <vm>

Parameters

<vm>: The VM's name, from shako vm ls.

Examples

Wake a VM. An SSH login or a request to a public port also wakes it.

shako vm wake web1

Wake two VMs together, before a script runs.

shako vm wake web1 && shako vm wake api

shako vm restart

Restart a VM: a clean shutdown, then a boot from its disk. Its running programs stop, and its files stay.

Usage

shako vm restart <vm>

Parameters

<vm>: The VM's name, from shako vm ls.

Examples

Restart a VM. Its running programs stop, and its files stay.

shako vm restart web1

Rename a VM, then restart it, so that the host name in the VM changes too.

shako vm rename web1 site && shako vm restart site

shako vm resize

Change size: the VM restarts, and its disk follows the new memory.

Usage

shako vm resize <vm> [flags]

Parameters

<vm>: The VM's name, from shako vm ls.
--size <size>: The new size: micro 1cpu/1G/10G disk, small 1cpu/2G/20G disk, mid 2cpu/4G/40G disk, large 4cpu/8G/80G disk.
--cpus <cpus>: Custom vCPUs: 1 or an even number. Only the vCPUs change.
--memory <memory>: Custom memory, for example 3G or 1536M. The disk is 10 GB per GB of memory. Only the memory and the disk change.
--restart: Allow restarting a running or sleeping VM.

Examples

Make a VM bigger. The VM restarts.

shako vm resize web1 --size large --restart

Give a VM 6 GB of memory. Its disk grows to 60 GB.

shako vm resize web1 --memory 6G --restart

Give a VM 1 vCPU.

shako vm resize web1 --cpus 1 --restart

shako vm set

Change sleep policy.

Usage

shako vm set <vm> [flags]

Parameters

<vm>: The VM's name, from shako vm ls.
--sleep <sleep>: When the VM sleeps. idle: when it is quiet; manual: only on request; never: it is always on, and restarts after a reboot or a crash.
--idle <idle>: The quiet time before the VM sleeps, for example 15m or 2h.

Examples

Sleep after 30 quiet minutes.

shako vm set web1 --sleep idle --idle 30m

Keep a VM always on, for example for a bot or a server.

shako vm set bot --sleep never

Sleep only on request.

shako vm set web1 --sleep manual

shako vm rename

Give a VM a new name. Its SSH name and the URLs of its public ports change too, and the old ones stop working.

Usage

shako vm rename <vm> <new_name>

Parameters

<vm>: The VM's name, from shako vm ls.
<new_name>: The new name, by the rule of a new VM's name.

Examples

Rename a VM. Its old SSH name and the old URLs of its public ports stop working.

shako vm rename web1 site

Rename a VM, then show the new URLs of its public ports.

shako vm rename web1 site && shako port ls site

shako vm cp

Copy a VM: a new VM whose disk starts as a copy-on-write copy of the source VM's disk. It gets the size, image and agents of the source VM, and boots with new SSH host keys.

Usage

shako vm cp <source> <name> [flags]

Parameters

<source>: The VM to copy, from shako vm ls.
<name>: The new VM's name: a-z, 0-9 and single hyphens, starting with a letter, at most 31 characters. It is in the VM's SSH name and in the URLs of its public ports.
--sleep <sleep>: When the VM sleeps. idle: when it is quiet; manual: only on request; never: it is always on, and restarts after a reboot or a crash (default: the sleep policy of the source VM).
--idle <idle>: The quiet time before the VM sleeps, for example 15m or 2h (default: the quiet time of the source VM).
--no-wait: Return before the guest's SSH is up.

Examples

Copy a VM, for example to try a risky change on the copy.

shako vm cp web1 web1-test

A copy that sleeps after 5 quiet minutes.

shako vm cp web1 web1-test --idle 5m

Return at once, before the copy's SSH is up.

shako vm cp web1 web2 --no-wait

shako vm logs

The VM's console output.

Usage

shako vm logs <vm> [flags]

Parameters

<vm>: The VM's name, from shako vm ls.
-n, --lines <lines>: How many of the last lines to show (default 100, at most 10000).

Examples

The last 100 lines of the VM's console.

shako vm logs web1

The last 500 lines.

shako vm logs web1 -n 500

Find errors in the console output.

shako vm logs web1 -n 1000 | grep -i error

shako vm usage

Awake hours and GB-hours per VM.

Usage

shako vm usage

Examples

Awake hours and GB-hours of each VM, and the total.

shako vm usage

The rows of one VM, without the total.

shako vm usage | grep web1

shako vm rm

Delete a VM and its disk.

Usage

shako vm rm <vm> [flags]

Parameters

<vm>: The VM's name, from shako vm ls.
--yes: Confirm the delete. Without --yes, nothing is deleted.

Examples

Delete a VM, its disk and its public ports. You cannot undo this.

shako vm rm web1-test --yes

Without --yes, nothing is deleted: the CLI only tells what the delete does.

shako vm rm web1-test

SSH Into a VM

Each VM is a plain SSH host. After shako login, ssh, scp, sftp and port forwarding work as on any server.

ssh

Log in to a VM, or run one command in it. A sleeping VM wakes first. In the VM you are the user shako, and sudo gives root with no password.

Usage

ssh <vm>.<tenant>.shako.dev [command]

Parameters

<vm>: The VM's name, from shako vm ls.
<tenant>: Your account's name, from shako whoami.
[command]: A command to run in the VM, in place of a shell.

Examples

ssh web1.maya.shako.dev

Run one command.

ssh web1.maya.shako.dev df -h

Install a package as root.

ssh web1.maya.shako.dev sudo apt-get install -y ripgrep

scp, sftp, rsync

Copy files between this computer and a VM. A path in a VM is <vm>.<tenant>.shako.dev:<path>.

Usage

scp <from> <to>

Parameters

<from>: The file or folder to copy: a path on this computer or in a VM.
<to>: Where the copy goes: a path on this computer or in a VM.
-r: Copy a folder and all that is in it.

Examples

Copy a file to the home folder of the VM.

scp ./app.tar.gz web1.maya.shako.dev:~/

Copy a folder from the VM to this computer.

scp -r web1.maya.shako.dev:~/site ./site

Copy only the changed files with rsync. The VM needs rsync too: install it once.

ssh web1.maya.shako.dev sudo apt-get install -y rsync && rsync -avz ./site/ web1.maya.shako.dev:~/site/

ssh -L

Open a private port of a VM on this computer, through SSH. Use it for a database or an app that only you use: the port stays private.

Usage

ssh -N -L <local-port>:localhost:<vm-port> <vm>.<tenant>.shako.dev

Parameters

<local-port>: The port on this computer.
<vm-port>: The port in the VM.
-N: Only forward the port, and run no command.

Examples

Open the VM's Postgres at localhost:5432 on this computer.

ssh -N -L 5432:localhost:5432 web1.maya.shako.dev

See a private dev server at http://localhost:3000.

ssh -N -L 3000:localhost:3000 web1.maya.shako.dev

Forward two ports with one connection.

ssh -N -L 5432:localhost:5432 -L 6379:localhost:6379 web1.maya.shako.dev

Ports and Public URLs

A public port gets its own HTTPS address, https://<vm>-<port>--<tenant>.shakoapp.dev. Anyone with the address can open it.

shako port ls

List a VM's ports, or only one port.

Usage

shako port ls <vm> [port]

Parameters

<vm>: The VM's name, from shako vm ls.
[port]: Show only this port, and check if a program listens on it.

Examples

The public ports of a VM, and the common ports that listen.

shako port ls web1

One port: is it public, and does a program listen on it?

shako port ls web1 8000

shako port public

Make a port public: anyone can open https://<vm>-<port>--<tenant>.<apps domain>.

Usage

shako port public <vm> <port>

Parameters

<vm>: The VM's name, from shako vm ls.
<port>: The port in the VM, 1 to 65535. A program must listen on it on 0.0.0.0, not 127.0.0.1.

Examples

Share port 3000 at https://web1-3000--maya.shakoapp.dev.

shako port public web1 3000

Share the Hermes dashboard of the VM assistant.

shako port public assistant 9119

shako port private

Make a public port private again.

Usage

shako port private <vm> <port>

Parameters

<vm>: The VM's name, from shako vm ls.
<port>: A public port of the VM.

Examples

Make port 3000 private again. Its URL stops working.

shako port private web1 3000

Make a database port private, and reach it only from this computer through SSH.

shako port private web1 5432 && ssh -N -L 5432:localhost:5432 web1.maya.shako.dev

Agent Sessions and the Screen

The terminal sessions of a VM, the same ones as in the web workspace. A session runs an agent or a shell, and it keeps running when you leave it.

shako session new

Start a session with a name in a folder and attach to it. To leave the session running, close the terminal or type ~. at the start of a line (ssh's escape).

Usage

shako session new <vm> <session> [flags]

Parameters

<vm>: The VM's name, from shako vm ls.
<session>: The new session's name, for example api or fix-login. No other session of the VM may have it.
--agent <agent>: The agent to run: claude, codex, opencode, pi, openclaw, hermes. The VM must have it. Default: a shell.
--dir <dir>: The folder in the VM to start in, an absolute path (default /home/shako). It must exist, unless --mkdir.
--mkdir: Make the folder first (and the folders above it).

Examples

Start Claude Code in a new session api, in a new folder.

shako session new web1 api --agent claude --dir /home/shako/api --mkdir

A shell in the home folder.

shako session new web1 shell

Codex in a folder that exists.

shako session new web1 fix-login --agent codex --dir /home/shako/app

shako session ls

List a VM's sessions.

Usage

shako session ls <vm>

Parameters

<vm>: The VM's name, from shako vm ls.

Examples

List the sessions of a VM. The web workspace shows the same sessions.

shako session ls web1

List the sessions, then attach to one.

shako session ls web1 && shako session attach web1 api

shako session attach

Attach to a session. To leave the session running, close the terminal or type ~. at the start of a line (ssh's escape).

Usage

shako session attach <vm> <session>

Parameters

<vm>: The VM's name, from shako vm ls.
<session>: The session's name, from shako session ls.

Examples

Attach to the session api. To leave it running, close the terminal or type ~. at the start of a line.

shako session attach web1 api

Attach to a session that you started in the web workspace.

shako session attach web1 dashboard

shako session rename

Give a session a new name.

Usage

shako session rename <vm> <session> <new_name>

Parameters

<vm>: The VM's name, from shako vm ls.
<session>: The session's name, from shako session ls.
<new_name>: The new name. No other session of the VM may have it.

Examples

Rename the session api to api-v2.

shako session rename web1 api api-v2

Give a shell session a name that tells what it does.

shako session rename web1 shell build

shako session rm

Delete a session: end it and the program in it.

Usage

shako session rm <vm> <session>

Parameters

<vm>: The VM's name, from shako vm ls.
<session>: The session's name, from shako session ls.

Examples

End the session api and the program in it.

shako session rm web1 api

End two sessions.

shako session rm web1 api && shako session rm web1 shell

shako screen open

Forward the VM's screen to a port on this computer for a VNC viewer, until Ctrl-C. Only a VM with agents and size mid or bigger has a screen.

Usage

shako screen open <vm> [flags]

Parameters

<vm>: The VM's name, from shako vm ls.
--take: Take over, for example for a login, a 2FA code or a CAPTCHA: the agents' browser and screen tools wait until this command stops.
--port <port>: The port on 127.0.0.1 (default 5901).

Examples

Watch the agents' screen: open vnc://127.0.0.1:5901 in a VNC viewer. On a Mac, Screen Sharing opens it.

shako screen open agents

Take over, for example for a login or a 2FA code. The agents' browser and screen tools wait until you stop the command.

shako screen open agents --take

Use another port on this computer.

shako screen open agents --port 5902

Agent Memory

Notes of up to 2000 tokens that Shako adds to each LLM request from your VMs, for every agent. Each request from your VMs to a model provider goes through Shako. Your login goes to the provider unchanged, and Shako does not keep it.

shako memory show

Show the notes, and if they are on.

Usage

shako memory show

Examples

Show the notes, and if they are on.

shako memory show

Read long notes one screen at a time.

shako memory show | less

shako memory edit

Change the notes in $EDITOR, and save them when the editor closes.

Usage

shako memory edit

Examples

Change the notes in your editor. They are saved when the editor closes.

shako memory edit

Use nano.

EDITOR=nano shako memory edit

Use VS Code.

VISUAL="code --wait" shako memory edit

shako memory set

Replace the notes with the text of a file.

Usage

shako memory set --file <file>

Parameters

--file <file>: Required. The file, or - for the standard input.

Examples

Replace the notes with the text of a file.

shako memory set --file notes.md

Replace the notes with one line.

echo "Always answer in bullet points." | shako memory set --file -

shako memory on

Add the notes to each LLM request from your VMs, also from your own programs.

Usage

shako memory on

Examples

Add the notes to each LLM request from your VMs.

shako memory on

Write the notes, then turn them on.

shako memory set --file notes.md && shako memory on

shako memory off

Stop adding the notes.

Usage

shako memory off

Examples

Stop adding the notes. The text stays.

shako memory off

Turn the notes off for one test, then on again.

shako memory off && shako memory on

SSH Keys

The keys that log in to your VMs and sign the requests of the CLI. shako login adds the key of this computer.

shako key ls

List your SSH keys.

Usage

shako key ls

Examples

List the SSH keys of your account: name, type and fingerprint.

shako key ls

Find one key by its name.

shako key ls | grep laptop

shako key add

Add a key with a name.

Usage

shako key add <key> --name <name>

Parameters

<key>: The public key or its .pub file.
--name <name>: Required. The key's name, for example the computer's name.

Examples

Add the key of a computer with no browser, from its .pub file.

shako key add ./build-server.pub --name build-server

Add a key from its text.

shako key add "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... ci@runner" --name ci

shako key rm

Remove the key with this name.

Usage

shako key rm <name>

Parameters

<name>: The key's name, from shako key ls.

Examples

Remove a key. It cannot log in after that.

shako key rm old-laptop

Find the key's name first.

shako key ls && shako key rm ci

This Computer

The settings of the CLI on this computer.

shako config show

Show the API and the key that this device uses.

Usage

shako config show

Examples

Show the API and the SSH key that this computer uses.

shako config show

Change the key, then check it.

shako config set --key ~/.ssh/shako_ed25519 && shako config show

shako config set

Set the API, the key or both.

Usage

shako config set [flags]

Parameters

--api <api>: The address of the Shako API (default https://api.shako.dev).
--key <key>: The SSH key that signs your requests, e.g. ~/.ssh/id_ed25519.

Examples

Sign requests with another SSH key.

shako config set --key ~/.ssh/shako_ed25519

Go back to the default API.

shako config set --api https://api.shako.dev

Get Early Access

Shako is in early access. Leave your email to get on the list.