Shako From the Terminal

The shako CLI runs on macOS, Linux and Windows.

Install

macOS and Linux

curl -fsSL https://shako.dev/install.sh | sh

In a terminal. The script puts the CLI in ~/.local/bin, adds that folder to your PATH, and needs no sudo.

Windows

irm https://shako.dev/install.ps1 | iex

In PowerShell. The script puts shako.exe in %LOCALAPPDATA%\shako\bin, adds that folder to your PATH, and needs no admin. ssh and scp come with Windows 10 and 11.

The CLI is one file, with nothing else to install. Or download it for your computer and put it in a folder of your PATH: macOS (Apple silicon), macOS (Intel), Linux (x86-64), Linux (ARM64), Windows (x64), Windows (ARM64).

Quick Start

  1. shako login

    Connect this computer to your account.

  2. shako vm create web1 --agent claude

    Create a VM with Claude Code.

  3. ssh web1.maya.shako.dev

    Log in, as to any server.

  4. shako port share web1 3000 public

    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

Log in this device: approve it in the workspace, then set up ssh to your VMs.

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

Log in this computer: approve it in the workspace, which opens in the browser. Then plain ssh to your VMs works.

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 tenants, your role in each, 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 update

Replace this CLI with the newest build. In a Shako VM (with sudo), also Shako's own tools in the VM.

Usage

shako update

Examples

Replace this CLI with the newest build. If the download or the new file fails, the CLI does not change.

shako update

Update, then check the version.

shako update && shako version

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: small 1cpu/2G/16G disk, mid 2cpu/4G/32G disk, large 4cpu/8G/64G disk, xl 4cpu/16G/128G disk (default small).
--cpus <cpus>
Custom vCPUs: 1 or an even number. It replaces the vCPUs of the size.
--memory <memory>
Custom memory, for example 3G or 2560M. The disk is 8 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. auto: when it is quiet; never: it stays on, and restarts after a reboot or a crash. With both, shako vm sleep and shako vm wake work at once (default auto).
--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>
An AI agent or a coding agent to put in the VM: claude, codex, opencode, pi, kiro, 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).
--isolated
The key in the VM acts nowhere: no shako commands and no SSH to other VMs from the VM. SSH into the VM, the internet and its URLs still work.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Create a VM of the default size, Small.

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: the VMs of all your tenants.

Usage

shako vm ls [flags]

Parameters

--tenant <tenant>
Only the VMs of this tenant.

Examples

List the VMs of all your tenants: state, size, disk, sleep policy, last activity and agents.

shako vm ls

Only the VMs that are awake.

shako vm ls | grep awake

Only the VMs of one tenant.

shako vm ls --tenant acme

shako vm info

Show one VM.

Usage

shako vm info <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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 crons

List the crons in a VM (cron and the schedulers of its agents) and its next wake. The box asks an awake VM now. A sleeping VM does not wake: the list is the one of its last sleep.

Usage

shako vm crons <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

List the crons in a VM: their source, schedule and next run, and when the box wakes the VM next.

shako vm crons assistant

The crons of two VMs, one after the other.

shako vm crons assistant && shako vm crons web1

shako vm sleep

Put a VM to sleep now.

Usage

shako vm sleep <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

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

shako vm restart web1

Restart a VM, then log in to it again.

shako vm restart web1 && ssh web1.maya.shako.dev

shako vm update

Update Shako's own tools in a VM (shako-session, shako-wake) and its shako CLI to the build of main, over ssh. The files in the VM and the running sessions stay. New sessions use the new tools.

Usage

shako vm update <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Give a VM the newest Shako tools, for example the session status in the web workspace. Your files stay.

shako vm update web1

Update two VMs.

shako vm update web1 && shako vm update api

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: small 1cpu/2G/16G disk, mid 2cpu/4G/32G disk, large 4cpu/8G/64G disk, xl 4cpu/16G/128G disk.
--cpus <cpus>
Custom vCPUs: 1 or an even number. Only the vCPUs change.
--memory <memory>
Custom memory, for example 3G or 2560M. The disk is 8 GB per GB of memory. Only the memory and the disk change.
--restart
Allow restarting a running or sleeping VM.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the 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, if crons and chat messages wake the VM, if the VM is isolated, and its backups.

Usage

shako vm set <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--sleep <sleep>
When the VM sleeps. auto: when it is quiet; never: it stays on, and restarts after a reboot or a crash. With both, shako vm sleep and shako vm wake work at once.
--idle <idle>
The quiet time before the VM sleeps, for example 15m or 2h.
--wake-on-cron <wake_on_cron>
On (the default): after each sleep, the VM wakes 2 minutes before its next cron job. off: it does not. On for a sleeping VM starts at its next sleep.
--wake-on-chat <wake_on_chat>
On or off: wake the VM when a chat message comes (default on).
--isolated <isolated>
On: the key in the VM acts nowhere: no shako commands and no SSH to other VMs from the VM. SSH into the VM, the internet and its URLs still work. off: the VM acts as you again. The change is at once, with no reboot.
--backup <backup>
On (the default): each night, Shako backs up the VM if its disk changed. off: no new backups, and the old backups go 7 days after they were taken.
--after-delete <after_delete>
What happens to the VM's backups when you delete the VM. keep-7d (the default): they stay 7 days, then Shako erases them. erase: Shako erases them within a few minutes. After an erase, the storage keeps the deleted data 7 more days, then deletes it.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Sleep after 30 quiet minutes.

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

A VM that never sleeps, for example for a bot or a server.

shako vm set bot --sleep never

Keep a VM asleep through its cron jobs.

shako vm set web1 --wake-on-cron off

shako vm rename

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

Usage

shako vm rename <vm> <new_name> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
<new_name>
The new name, by the rule of a new VM's name.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

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

shako vm rename web1 site

Rename a VM, then show the new URLs of its shared 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. auto: when it is quiet; never: it stays on, and restarts after a reboot or a crash. With both, shako vm sleep and shako vm wake work at once (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.
--isolated
The key in the VM acts nowhere: no shako commands and no SSH to other VMs from the VM. SSH into the VM, the internet and its URLs still work. The source must be isolated: its copy is isolated also without this flag.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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).
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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 and asleep hours, RAM GB-hours and cost per VM.

Usage

shako vm usage [flags]

Parameters

--range <range>
The time: this week (from Monday), this month, or all (default).
--vm <vm>
Only the VMs with this name, deleted ones too.
--days
Also the cost of each day, on this computer's clock.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

The hours awake and asleep of each VM with usage, and its RAM GB-hours (memory times those hours), and its cost in US dollars. One row holds all the deleted VMs with one name. The most awake GB-hours come first, then the most asleep. Then the totals, with the total cost.

shako vm usage

The cost of the VMs named web1 this month, deleted ones too, and of each day.

shako vm usage --range month --vm web1 --days

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.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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

Delete a VM, and its backups within a few minutes, not after 7 days.

shako vm set web1-test --after-delete erase && shako vm rm web1-test --yes

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

Log in to a VM.

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

Backups

A backup is a copy of a VM's disk, kept outside its box. A restore puts the disk back to a backup, and the VM restarts. With backups on, Shako backs up the current disk first, so you can undo a restore. shako vm set --backup and --after-delete are the privacy settings of a VM.

shako backup ls

List a VM's backups, newest first: the ID, the time on this computer's clock, the kind (nightly, manual or pre-restore) and the data that it added to the store. Then the backup or restore that runs now, or the last one if it failed.

Usage

shako backup ls <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

List a VM's backups: the ID, the time, the kind and the data that each one added. Then the backup or restore that runs now.

shako backup ls web1

Only the nightly backups.

shako backup ls web1 | grep nightly

shako backup create

Back up a VM now. The VM keeps running. This backup replaces the last manual backup. The command waits until the backup is done.

Usage

shako backup create <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--no-wait
Return at once. The backup goes on, and shako backup ls shows it.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Back up a VM now, for example before a risky change. The VM keeps running, and the CLI waits until the backup is done.

shako backup create web1

Start the backup and return at once. Then see how it goes.

shako backup create web1 --no-wait && shako backup ls web1

shako backup restore

Put a VM's disk back to one of its backups. The VM restarts, and the files that changed after the backup go back. Shako backs up the current disk first (kind pre-restore), so you can undo. With backups off for the VM (shako vm set --backup off), it does not, and you cannot undo. Without --yes, the CLI asks first.

Usage

shako backup restore <vm> <id> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
<id>
The backup's ID, from shako backup ls.
--yes
Do not ask first.
--no-wait
Return at once. The restore goes on, and shako backup ls shows it.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Put a VM's disk back to a backup, with its ID from shako backup ls. The CLI asks first, and the VM restarts.

shako backup restore web1 9f3c1a2e

Restore with no question, for example in a script.

shako backup restore web1 9f3c1a2e --yes

Undo a restore: restore the pre-restore backup that it made of the disk of before.

shako backup restore web1 7d01b4c9

shako backup erase

Delete every backup of a VM now. You cannot undo this. The VM stays, and with backups on, the next night backs it up again. The storage keeps the deleted data 7 more days, then deletes it. Without --yes, the CLI asks first.

Usage

shako backup erase <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--yes
Do not ask first.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Erase every backup of a VM now. The CLI asks first, and the VM stays. The storage deletes the last copies within 7 days.

shako backup erase web1

Stop the backups of a VM, then erase the old ones now with no question.

shako vm set web1 --backup off && shako backup erase web1 --yes

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] [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
[port]
Show only this port, and check if a program listens on it.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

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

shako port ls web1

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

shako port ls web1 8000

shako port share

Share a port at a URL, on your private network or for the internet.

Usage

shako port share <vm> <port> <access> [flags]

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.
<access>
Public: anyone on the internet can open https://<vm>-<port>--<tenant>.<apps domain>. private: only your devices can open https://<vm>-<port>--<tenant>.net.<apps domain>.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Share port 3000 at https://web1-3000--maya.shakoapp.dev. Anyone can open it.

shako port share web1 3000 public

Share an admin page at https://auction-8080--maya.net.shakoapp.dev. Only your devices can open it.

shako port share auction 8080 private

shako port unshare

Stop sharing a port. Its URL stops working.

Usage

shako port unshare <vm> <port> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
<port>
A shared port of the VM.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Stop sharing port 3000. Its URL stops working.

shako port unshare web1 3000

Stop sharing a database port, and reach it only from this computer through SSH.

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

Your Private Network

A private port opens only on your devices, with no password, at https://<vm>-<port>--<tenant>.net.shakoapp.dev. Add this computer once. Its tunnel stays on, and it carries only the traffic to Shako.

shako device add

Add this computer to your private network. It installs WireGuard if it is missing, and starts a tunnel that stays on, also after a reboot. It uses sudo.

Usage

shako device add [name] [flags]

Parameters

[name]
The device's name (default: this computer's host name).
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Add this computer to your private network, with its host name as the device's name.

shako device add

Give the device a name, then share a port that only your devices can open.

shako device add work-laptop && shako port share auction 8080 private

shako device ls

List your devices.

Usage

shako device ls [flags]

Parameters

--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

List your devices: name, the day you added each one, and the last time its tunnel was up.

shako device ls

Find one device by its name.

shako device ls | grep laptop

shako device rm

Remove a device. Its tunnel stops at once. On this computer, the tunnel's files go too.

Usage

shako device rm <name> [flags]

Parameters

<name>
The device's name, from shako device ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Remove a device. Its tunnel stops at once.

shako device rm old-laptop

Find the device's name first.

shako device ls && shako device rm old-laptop

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, kiro, 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).
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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: the name, the agent, and the status of the program in it (working, blocked, done or idle). A shell, or a session from before shako vm update, has no status.

Usage

shako session ls <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

List the sessions of a VM and the status of each agent. 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> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
<session>
The session's name, from shako session ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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> [flags]

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.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
<session>
The session's name, from shako session ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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).
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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

shako build open

Open the VM's build page (workspace.shako.dev/build) in this computer's browser. Only a VM with an agent has T3 Code.

Usage

shako build open <vm> [flags]

Parameters

<vm>
The VM's name, from shako vm ls.
--no-browser
Only print the link.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Open T3 Code in the VM agents, in this computer's browser. Code with its agents there.

shako build open agents

Only print the link, for example to open it on another computer.

shako build open agents --no-browser

Agent Memory

Notes of up to 2000 tokens that Shako adds to each LLM request from your VMs, for every agent. While memory is on, 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. While memory is off, the requests go straight to the provider.

shako memory show

Show the notes, and if they are on.

Usage

shako memory show [flags]

Parameters

--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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 [flags]

Parameters

--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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> [flags]

Parameters

--file <file>
Required. The file, or - for the standard input.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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

Send each LLM request from your VMs, also from your own programs, through Shako, which adds the notes.

Usage

shako memory on [flags]

Parameters

--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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: the LLM requests from your VMs go straight to the providers.

Usage

shako memory off [flags]

Parameters

--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

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

Secrets

A secret, such as a GitHub token, that your VMs use but cannot read. Each VM gets a placeholder, and Shako puts the value in place of it in the requests to the hosts of the secret. The value never goes into a VM.

shako secret set

Add a secret or replace it. The value comes from the standard input, or else the CLI asks for it and does not show what you type. Each VM gets the variable NAME=shako-secret-NAME, and Shako puts the value in place of shako-secret-NAME in each request to the hosts. The value never goes into a VM.

Usage

shako secret set <secret> --host <host> [flags]

Parameters

<secret>
The secret's name, also the name of the variable in your VMs, for example GH_TOKEN: A-Z, 0-9 and _, not first a digit, at most 64 characters.
--host <host>
Required. A host that gets the value: github.com or api.github.com. Give --host for each host.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Give your VMs the GitHub login of this computer. Then git clone, git push and gh work with your private repositories in each VM, and no VM has the token.

gh auth token | shako secret set GH_TOKEN --host github.com --host api.github.com

Type the value: the CLI asks for it and does not show it.

shako secret set GH_TOKEN --host github.com --host api.github.com

Take the value from a file. With github.com only, git works, but gh does not: gh uses api.github.com.

shako secret set GH_TOKEN --host github.com < token.txt

shako secret ls

List your secrets: the name, the hosts, the last 4 characters of a long value, and when it changed. No command shows a value.

Usage

shako secret ls [flags]

Parameters

--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

List your secrets: the name, the hosts, the last 4 characters of a long value, and when it changed.

shako secret ls

Check that a secret is there.

shako secret ls | grep GH_TOKEN

shako secret rm

Remove a secret. Shako stops putting its value in the requests of your VMs.

Usage

shako secret rm <secret> [flags]

Parameters

<secret>
The secret's name, from shako secret ls.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Remove a secret. Shako stops putting its value in the requests of your VMs.

shako secret rm GH_TOKEN

Find the secret's name first.

shako secret ls && shako secret rm GH_TOKEN

Credit

Your VMs use prepaid credit. Awake, a VM pays for its memory and its disk. Asleep, it pays for its disk only.

shako credit show

Show the balance, the credit, and the cost of your VMs since billing started.

Usage

shako credit show [flags]

Parameters

--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Show what is left of your credit, and what your VMs used.

shako credit show

Show only the balance.

shako credit show | head -1

shako credit add

Add credit: pay on a Stripe page in the browser. The credit goes up when Stripe tells Shako that it is paid.

Usage

shako credit add <AMOUNT> [flags]

Parameters

<AMOUNT>
The US dollars to add: 5, 10, 25, 50.
--no-browser
Only print the link of the payment page.
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Add $10 of credit: pay on the Stripe page that opens in the browser.

shako credit add 10

Only print the link of the payment page, and open it on another computer.

shako credit add 25 --no-browser

shako credit invoice

Save the PDF invoice of a month: each VM's usage and cost.

Usage

shako credit invoice [MONTH] [flags]

Parameters

[MONTH]
The month, YYYY-MM (default: this month, on this computer's clock).
-o, --output <output>
The file to write (default: shako-invoice-<name>-<month>.pdf in this folder).
--tenant <tenant>
The tenant, from shako tenant ls. You need it when you have more than one tenant. In a Shako VM, the default is the tenant of the VM.

Examples

Save the PDF invoice of this month so far, in this folder.

shako credit invoice

Save the invoice of October 2026 as oct.pdf.

shako credit invoice 2026-10 -o oct.pdf

Tenants

A tenant has its own VMs, credit and invoices. You can own many tenants and share one with other accounts: each one accepts with the link of an email. With more than one tenant, a command that acts in a tenant needs --tenant.

shako tenant ls

List your tenants, your role in each (owner or member), and the default: the tenant of a command with no --tenant.

Usage

shako tenant ls

Examples

List your tenants and your role in each: owner or member.

shako tenant ls

Only the tenants that you own.

shako tenant ls | grep owner

shako tenant create

Create a tenant that you own. It has its own VMs, credit and invoices. Only the first tenant that you create gets the free credit, one time.

Usage

shako tenant create <name>

Parameters

<name>
The new tenant's name: a-z, 0-9 and single hyphens, at most 20 characters. It is in the SSH names and the URLs of its VMs.

Examples

Make a second tenant, with its own VMs, credit and invoices. It starts at $0.

shako tenant create acme

Make a tenant, then a VM in it.

shako tenant create acme && shako vm create web1 --tenant acme

shako tenant rm

Delete a tenant that you own. It must have no VMs, and no other members or invites. Its credit, secrets, devices and agent memory go.

Usage

shako tenant rm <name> [flags]

Parameters

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

Examples

Delete a tenant that you own. It must have no VMs, and no other members or invites. You cannot undo this.

shako tenant rm acme --yes

Delete the last VM of a tenant, then the tenant.

shako vm rm web1 --yes --tenant acme && shako tenant rm acme --yes

shako tenant share

Invite another account to a tenant: its VMs, ports, devices and agent memory. The account gets an email, and it is a member when it opens the link. It must have logged in to Shako once. Only the owner shares.

Usage

shako tenant share <name> <email>

Parameters

<name>
The tenant's name, from shako tenant ls.
<email>
The email of the account.

Examples

Invite a colleague to a tenant. They must have logged in to Shako once, and they accept with the link of the email.

shako tenant share acme bob@example.com

Invite an account, then show the accounts of the tenant: it is invited until it accepts.

shako tenant share acme bob@example.com && shako tenant members acme

shako tenant unshare

Stop sharing a tenant with an account, or cancel its invite. Its VMs stay in the tenant, and their keys and its devices stop working there. Only the owner unshares. A member can leave: give your own email.

Usage

shako tenant unshare <name> <email>

Parameters

<name>
The tenant's name, from shako tenant ls.
<email>
The email of the account.

Examples

Stop sharing a tenant with an account, or cancel its invite. Its VMs stay in the tenant.

shako tenant unshare acme bob@example.com

Leave a tenant that another account shares with you.

shako tenant unshare acme you@example.com

shako tenant members

List the accounts of a tenant and their roles.

Usage

shako tenant members <name>

Parameters

<name>
The tenant's name, from shako tenant ls.

Examples

Show the accounts of a tenant and their roles.

shako tenant members acme

Only the members, not the owner.

shako tenant members acme | grep member

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, then the keys of the VMs of the other members of your tenants.

Usage

shako key ls

Examples

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

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. The key of a VM stays in shako key ls, off: it acts nowhere.

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

Join with your email, or join us on Discord.