Skip to content

Getting Started

This tutorial walks you through installing jailoc and running your first sandboxed workspace. By the end, you'll have a coding agent (OpenCode) running in an isolated micro-VM, working on your project directory.

Prerequisites

You need one of these hosts:

  • macOS on Apple Silicon. jailoc uses Hypervisor.framework.
  • Linux on amd64 or arm64 with KVM. Your user needs read and write access to /dev/kvm. ARM64 Linux support is experimental.

Docker Engine on the host is optional. When it's running, jailoc builds workspace images with it; otherwise it builds them in a separate builder VM.

Install jailoc

Install jailoc with Homebrew on macOS or Linux:

brew install --cask seznam/tap/jailoc

Alternatively, download the archive for your platform from GitHub Releases, extract it, and place the jailoc binary on your PATH. To build from source instead, see How to install jailoc.

After installation, confirm it's on your PATH:

jailoc --version

Run your first workspace

The quickest way to get started is to run jailoc without any arguments from your project directory:

cd ~/myproject
jailoc

Here's what happens on first run:

  1. First-time setup: if ~/.config/jailoc/config.toml doesn't exist or still matches the unmodified default template, jailoc offers to run the interactive jailoc setup wizard (jailoc wizard) to choose your coding agent, Git/SSH/GPG forwarding, network policy, and initial workspace path. You can also run jailoc setup directly at any time to add another workspace.
  2. Workspace prompt: if the current directory isn't part of any configured workspace, jailoc asks whether to add it. Confirm, and the workspace is saved to your config.
  3. Runtime unpacking: jailoc unpacks the VM runtime embedded in its binary into ~/.cache/jailoc-vm/runtime/. This happens once.
  4. Image build: jailoc builds the workspace image, with host Docker or in a builder VM, and unpacks it into a VM root filesystem.
  5. VM start: jailoc boots the workspace VM, shares your project directory into it, and starts the network broker.
  6. Attach: jailoc opens an agent session over SSH and attaches your terminal to it.

Note

Your project directory is shared at its original path inside the VM. If your project lives at /home/you/myproject, the agent sees it at the same path. Running jailoc from a subdirectory (for example ~/myproject/src) opens that subdirectory in the agent instead of the workspace root.

Detach and come back

Press Ctrl-b, then d, to detach from the session. The agent keeps running inside the VM. Run jailoc again from the same directory to reattach to it.

To see the sessions running in the workspace:

jailoc sessions

Use subcommands directly

The bare jailoc shortcut is convenient, but you can also drive each step explicitly:

# Start the workspace VM in the background
jailoc up

This separation is useful when you want to start the workspace and come back to it later.

Other subcommands worth knowing:

jailoc status   # show the state of the workspace VM
jailoc logs     # show workspace logs
jailoc down     # stop the workspace VM

jailoc down keeps the VM's home state, such as agent conversations, logins and caches, for the next start. jailoc down --purge deletes it.

What's running

When the workspace is up, these pieces are active:

  • The workspace VM runs jailoc-guest as its init. It serves SSH to jailoc, and each agent session runs as the agent user (UID 1000), which can use sudo inside the VM.
  • The network broker runs on the host. All of the VM's traffic goes through it. Public destinations are reachable, but private and reserved address ranges are blocked unless you allow them.

Next steps

Now that you have a workspace running, you can dig into configuration: