Skip to content

Commit a57e064

Browse files
alexellisalexellis
committed
Show coding agents on both Mac/Linux
Signed-off-by: Alex Ellis (OpenFaaS Ltd) <alexellis2@gmail.com>
1 parent 0613cca commit a57e064

File tree

3 files changed

+170
-7
lines changed

3 files changed

+170
-7
lines changed

‎docs/examples/coding-agents.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Sandboxing Coding Agents
2+
3+
You can run coding agents like [Claude Code](https://code.claude.com/docs/en/overview), [OpenCode](https://opencode.ai/), and [Amp](https://amp.dev/) inside Slicer VMs.
4+
This page applies to both Slicer for Linux and Slicer for Mac.
5+
6+
Running an agent inside a VM means you don't need to grant broad permissions on your host CLI. The agent gets its own kernel and filesystem, and can't touch your SSH keys, cloud credentials, or browser sessions.
7+
8+
## `slicer workspace`: generic workspace runner
9+
10+
`slicer workspace` is a generic command that bootstraps a fresh VM for your current project workspace. It copies your working directory into the VM and drops you into a shell so you can run a tool of your choice.
11+
12+
Use it when you want one-VM-per-task behavior without being tied to a specific agent binary. For example, use it for:
13+
14+
* trying out a new tool against a codebase
15+
* running a custom script-based agent
16+
* reproducing task-specific work in a disposable environment
17+
18+
Because it is generic, it’s a good fit when the built-in `slicer claude`, `slicer opencode`, etc. shortcuts don’t match your exact workflow.
19+
20+
## Automated agent and sandbox launches
21+
22+
Slicer has a number of experimental commands that do the following:
23+
24+
* Boot a new VM
25+
* Copy the current directory to the VM in the same relative path
26+
* Install the specified AI agent and copy in its config/auth files
27+
* Launch the agent in a shell (`slicer vm shell`)
28+
29+
Available agent commands:
30+
31+
* `slicer workspace`
32+
* `slicer amp`
33+
* `slicer copilot`
34+
* `slicer codex`
35+
* `slicer claude`
36+
* `slicer opencode`
37+
38+
If your agent (for example, Pi or Hermes) is not listed above, request support in the Discord, or use `slicer workspace` and install and configure your agent via a bash script or userdata.
39+
40+
To launch a new Slicer VM for Claude:
41+
42+
```bash
43+
mkdir -p ~/dev/
44+
cd ~/dev/
45+
git clone --depth=1 https://github.com/alexellis/arkade
46+
47+
cd arkade
48+
49+
slicer claude .
50+
```
51+
52+
When launching a VM for a coding agent, you can specify:
53+
54+
* `--tmux=none` - launch the agent directly in the shell
55+
* `--tmux=local` - launch a shell using tmux on the host (requires `brew install tmux` on macOS)
56+
* `--tmux=remote` - launch a shell using tmux on the VM
57+
58+
Tmux is a time-tested terminal tool and ideal for running processes in the background, and reconnecting to them later.
59+
60+
## Install agents manually
61+
62+
Shell into your VM and install agents with [arkade](https://github.com/alexellis/arkade):
63+
64+
```bash
65+
slicer vm shell slicer-1
66+
67+
# Install Claude Code
68+
arkade get claude --path /usr/local/bin
69+
70+
# Install OpenCode
71+
arkade get opencode --path /usr/local/bin
72+
```
73+
74+
Both binaries are installed into `/usr/local/bin` inside the VM. They persist across reboots if your base VM is persistent.
75+
76+
## Authenticate
77+
78+
### Claude Code with an API key
79+
80+
Set the `ANTHROPIC_API_KEY` environment variable inside the VM:
81+
82+
```bash
83+
export ANTHROPIC_API_KEY=sk-ant-...
84+
```
85+
86+
Add it to `~/.bashrc` to persist across sessions:
87+
88+
```bash
89+
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc
90+
```
91+
92+
Then run Claude Code:
93+
94+
```bash
95+
cd /home/ubuntu/host/code/my-project
96+
claude --dangerously-skip-permissions
97+
```
98+
99+
Inside the VM, `--dangerously-skip-permissions` is acceptable because the VM is the sandbox.
100+
101+
!!! note "Claude Max plan"
102+
The Claude Max subscription uses OAuth-based authentication. Run `claude` inside the VM and follow the interactive login flow. The auth token is stored inside the VM and does not affect your host.
103+
104+
### OpenCode
105+
106+
Authenticate with your provider of choice:
107+
108+
```bash
109+
opencode auth login --provider github --token <your-github-token>
110+
```
111+
112+
The auth config is stored at `~/.local/share/opencode/auth.json` inside the VM.
113+
114+
## Linux-specific workspace details
115+
116+
On Slicer for Linux, use the workspace mounting pattern defined for your host/group and the normal `slicer vm cp` flow for file movement.
117+
118+
Use:
119+
- your host filesystem access model (from your host/group config)
120+
- `slicer vm cp` for explicit copies into and out of ephemeral VMs
121+
122+
## Run headless agents non-interactively
123+
124+
For one-off and automated tasks, launch a sandbox instead of using your persistent VM:
125+
126+
```bash
127+
# Launch a sandbox
128+
slicer vm launch sbox
129+
130+
# Copy a repo in
131+
slicer vm cp ./my-project sbox-1:/home/ubuntu/my-project
132+
133+
# Run the agent
134+
slicer vm exec --uid 1000 --cwd /home/ubuntu/my-project sbox-1 -- \
135+
claude --dangerously-skip-permissions -p "Write tests for main.go"
136+
137+
# Copy results out
138+
slicer vm cp sbox-1:/home/ubuntu/my-project ./my-project-result
139+
140+
# Delete when done
141+
slicer vm delete sbox-1
142+
```
143+
144+
The sandbox has its own kernel and filesystem. If the agent does something unexpected, delete it and start fresh.
145+
146+
## Next steps
147+
148+
- [Sandboxes](/mac/sandboxes) - more on launching and managing ephemeral VMs
149+
- [Headless OpenCode on Slicer for Linux](/examples/opencode-agent) - one-shot agent execution via userdata and the exec API
150+
- [Headless Cursor CLI on Slicer for Linux](/examples/cursor-cli-agent) - running Cursor's CLI agent headlessly
151+
- [Trying Claude Code with Ollama](https://slicervm.com/blog/trying-claude-code-with-ollama) - using Claude Code with a local LLM backend

‎docs/mac/coding-agents.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,16 @@ You can run coding agents like [Claude Code](https://code.claude.com/docs/en/ove
44

55
Running an agent inside a VM means you don't have to pass `--dangerously-skip-permissions` on your Mac. The agent gets its own kernel and filesystem, and can't touch your SSH keys, cloud credentials, or browser sessions.
66

7+
## `slicer workspace`: generic workspace runner
8+
9+
`slicer workspace` is a generic command for booting a fresh VM and copying your current workspace into it. It is not limited to one specific agent binary.
10+
11+
Use it when you want:
12+
13+
* one-off or temporary VM environments
14+
* custom agent tooling that isn't covered by `slicer claude` / `slicer opencode` shortcuts
15+
* a reproducible workspace copy for isolated scripting or testing
16+
717
## Automated agent and sandbox launches
818

919
Slicer has a number of experimental commands that do the following:
@@ -15,13 +25,14 @@ Slicer has a number of experimental commands that do the following:
1525

1626
Available agent commands:
1727

28+
* `slicer workspace`
1829
* `slicer amp`
1930
* `slicer copilot`
2031
* `slicer codex`
2132
* `slicer claude`
2233
* `slicer opencode`
2334

24-
Finally, there's another option for custom AI agents `slicer workspace`
35+
If your agent (for example, Pi or Hermes) is not listed above, request support in the Discord, or use `slicer workspace` and install and configure your agent via a bash script or userdata.
2536

2637
To launch i.e. a new slicer VM for Claude:
2738

@@ -123,9 +134,9 @@ share_home: "~/code/"
123134
124135
Restart the daemon after changing this setting. The agent can only see projects under `~/code/`, not your SSH keys, cloud credentials, or dotfiles.
125136

126-
## Run agents in sandboxes
137+
## Run headless agents non-interactively
127138

128-
For one-off tasks, launch a sandbox instead of using your persistent VM:
139+
For one-off and automated tasks, launch a sandbox instead of using your persistent VM:
129140

130141
```bash
131142
# Launch a sandbox

‎mkdocs.yml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -99,16 +99,17 @@ nav:
9999
- Walkthrough: getting-started/walkthrough.md
100100
- Running in the background: getting-started/daemon.md
101101
- Examples:
102+
- AI/LLMs:
103+
- Sandboxing Coding Agents: examples/coding-agents.md
104+
- Ollama with a GPU: examples/gpu-ollama.md
105+
- Headless OpenCode Coding Agent: examples/opencode-agent.md
102106
- Kubernetes:
103107
- HA Kubernetes: examples/ha-k3s.md
104108
- Autoscaling Kubernetes: examples/autoscaling-k3s.md
105109
- Large scale Kubernetes: examples/large-scale-k3s.md
106110
- Multiple machine Kubernetes: examples/multiple-machine-k3s.md
107111
- K3s with a GPU: examples/k3s-gpu.md
108112
- OpenFaaS on K3s: examples/openfaas.md
109-
- AI/LLMs:
110-
- Ollama with a GPU: examples/gpu-ollama.md
111-
- Headless OpenCode Coding Agent: examples/opencode-agent.md
112113
- Productivity:
113114
- Remote Docker builds over SSH: examples/buildkit.md
114115
- Remote VSCode: examples/remote-vscode.md
@@ -166,7 +167,7 @@ nav:
166167
- Sleep behavior: mac/sleep.md
167168
- Tray integration: mac/tray-integration.md
168169
- Examples:
169-
- Coding agents: mac/coding-agents.md
170+
- Sandboxing Coding Agents: mac/coding-agents.md
170171
# extra:
171172
# analytics:
172173
# provider: google

0 commit comments

Comments
 (0)