<!-- From docs/getting-started.md at Loa Workspace v0.11.0, as released. -->

# Getting started: from nothing to a pushed change

Workspace is a small server you run on your own machine. Claude Code connects to it and gets a
fixed set of tools for one git repository: it can read, search, edit, run commands, commit and
push. Every command runs in a sandbox that can only write inside that repository, and your
GitHub token stays with the server, never with the model.

This page takes you from a bare machine to a change an agent made and pushed to GitHub. It
covers a Mac. Linux needs a few more steps as root, which are in [the install guide](install.md);
do those first, then follow this page from step 3 with the Linux paths in each step.

Two words this page uses:

- **The server** is the `workspace` program, running in the background. (Other pages call it
  the daemon.)
- **The repository** is the git repository you want the agent to work on. In the
  configuration it's called `root`.

## 1. What you need

- A Mac (Apple silicon or Intel), or a Linux machine with systemd.
- `gh`, signed in to GitHub, with access to `loaapp/workspace`. The repository is private, so
  only someone with access can download a release. Run `gh auth status` to check.
- Claude Code. Run `claude --version` to check.
- The repository you want the agent to work on, cloned on the same machine.
- Optional, to let the agent push: a GitHub token for that one repository. Create a
  fine-grained token (GitHub → Settings → Developer settings → Personal access tokens →
  Fine-grained tokens). Under Repository access, choose only that repository. Under
  Permissions, set Contents to Read and write. Give it an expiry date.

  Use a fine-grained token, not a classic one. A classic token can reach every repository your
  account can, and the server logs a warning about it each time it starts. Without a token,
  the agent can still read, edit, run and commit; you push yourself.

## 2. Install

Find the newest release:

```
gh release list --repo loaapp/workspace
```

Then set `VERSION` to that release, and `SYSTEM` to your machine: `darwin_arm64` for Apple
silicon, `darwin_amd64` for an Intel Mac, `linux_amd64` or `linux_arm64` for Linux.

```
VERSION=v0.11.0
SYSTEM=darwin_arm64
mkdir -p ~/Downloads/workspace-release && cd ~/Downloads/workspace-release
gh release download "$VERSION" --repo loaapp/workspace \
  --pattern "workspace_*_${SYSTEM}.tar.gz" --pattern SHA256SUMS
tar -xzf "workspace_${VERSION}_${SYSTEM}.tar.gz" "workspace_${VERSION}_${SYSTEM}/install.sh"
sh "workspace_${VERSION}_${SYSTEM}/install.sh" "workspace_${VERSION}_${SYSTEM}.tar.gz"
```

The installer checks the download against `SHA256SUMS`, then installs into your home
directory, with no `sudo`:

- the program, at `~/.local/bin/workspace`
- a LaunchAgent, which is how macOS runs the server in the background
- an example configuration

It prints what it installed. It doesn't start the server. Check that it worked:

```
~/.local/bin/workspace --version
```

The commands on this page use the full path `~/.local/bin/workspace`, so they work even if
that folder isn't on your `PATH`.

**On Linux,** the installer only checks and unpacks the download, then prints the remaining
steps. They need root: a user for the server, a systemd unit, and directories under `/etc`
and `/var`. They're in [the install guide](install.md). Linux also needs git, bash,
bubblewrap 0.8 or later, and unprivileged user namespaces. Your clone must be owned by the
server's `workspace` user.

## 3. Point the server at your repository

Open the configuration file:

```
~/Library/Application Support/run.loa.workspace/config/workspace.yaml
```

(On Linux: `/etc/workspace/workspace.yaml`.)

Change two things:

1. **`root`:** the full path to your cloned repository, for example
   `/Users/you/code/my-app`. The server won't start until that folder exists.
2. **`author`:** the name and email the agent's commits will be made under. The example
   file uses a placeholder, `Workspace <workspace@example.invalid>`. Change it, or every
   commit will carry that placeholder.

Leave the file where the installer put it. The server hides that folder from every command,
so nothing the agent runs can read it.

Leave `data` as it is. If you ever move it, the server checks its length when it starts, and
it tells you the limit if the path is too long.

**To let the agent push,** add this block at the end of the file, starting at the left
margin. The example file has it commented out:

```yaml
git:
  remote: https://github.com/<you>/<repository>.git
  credential: git
  push: branch
```

- `remote` is the only place the agent can push to or fetch from. It must start with
  `https://` and can't contain a username. The server takes it from this file, never from the
  repository.
- `credential: git` refers to the token you'll store in the next step.
- `push: branch` turns on the `git_push` tool. Without this block, the agent has no
  `git_fetch` or `git_push`.

## 4. Store the GitHub token

Skip this step if you're not letting the agent push.

```
~/.local/bin/workspace secret set git --from-file - \
  --config "$HOME/Library/Application Support/run.loa.workspace/config/workspace.yaml"
```

Paste the token, press Enter, then press Ctrl-D. The token is read from your input, so it
never appears as an argument or in your shell history, and the command doesn't print it.

On a Mac, the token is stored in your login keychain. The first time the server reads it,
macOS asks whether to allow that. Choose **Always Allow**. The prompt can take a while to
appear, so watch for it when you start the server in step 6.

On Linux, the token is a file under the configuration's `secrets.dir` that only the server's
user can read.

## 5. Make the connection token

This is a different token from the GitHub one. It's the password Claude Code uses to talk to
the server. Make it once:

```
mkdir -p ~/.config/loa && chmod 700 ~/.config/loa
(umask 077; ~/.local/bin/workspace token new \
  --config "$HOME/Library/Application Support/run.loa.workspace/config/workspace.yaml" \
  > ~/.config/loa/workspace.token)
```

The command prints the token once, and the line above saves it straight to a file only you
can read, so it never appears on screen or in your history. The server stores only a hash
of it, so the token can't be shown again. If you lose it, run the command again: the new
token replaces the old one the next time the server starts.

## 6. Start the server

On a Mac:

```
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/run.loa.workspace.plist
tail -n 30 ~/Library/Logs/Workspace/workspace.err.log
```

The first command starts the LaunchAgent the installer put in place. The second shows the
server's log.

Each time the server starts, it tests its own sandbox: it tries to break out of it from
inside a command, several different ways. Each attempt should fail. In the log, that looks
like this, and it's what you want to see:

- one line per attempt, each ending `refused=true`
- `the confinement holds: every attempt from inside a command was refused`
- `serving`, with the address, the repository and the list of tools

If an attempt works, the server refuses to start. If it stops for any reason, the last line
of the log says why: for example, a `root` folder that doesn't exist, a sandbox that isn't
available, or a port that's already in use.

The server runs while you're logged in, and stops when you log out. To restart it, for
example after editing the configuration:

```
launchctl kickstart -k gui/$(id -u)/run.loa.workspace
```

To stop it and keep it from starting again:

```
launchctl bootout gui/$(id -u)/run.loa.workspace
```

**On Linux,** once the unit is installed as the install guide describes:

```
sudo systemctl enable --now workspace
sudo journalctl -u workspace -n 50
```

You should see the same lines.

The server listens on `127.0.0.1:7443`, which only this machine can reach. If the server runs
on a different machine from Claude Code, connect through an SSH tunnel:
`ssh -L 7443:127.0.0.1:7443 <machine>`.

## 7. Connect Claude Code

Add the server to Claude Code, under the name `loa-workspace`. (Claude Code reserves the name
`workspace` for itself.)

```
claude mcp add --transport http --scope user loa-workspace http://127.0.0.1:7443/ \
  --header "Authorization: Bearer $(cat ~/.config/loa/workspace.token)"
```

`--scope user` makes the server available in every directory. Then check it:

```
claude mcp list
```

`loa-workspace` should show as connected. If it shows as failed, either the server isn't
running (see step 6) or the token is wrong. A wrong token shows up in the server's log as a
refused request.

**About where the token ends up:** the shell reads the token file before `claude` runs, so
your history only records the file name. Claude Code then saves the header in its own
configuration, in plain text. If you'd rather keep the token out of every file, Claude Code
can instead run a command that supplies the header each time it connects (`headersHelper`
in a `.mcp.json`).

If you use `--scope project` instead, the server is saved to this directory's `.mcp.json`,
with the token in it in plain text. Never commit that file. Run `claude` in the directory
once to approve the server before `claude mcp list` shows it as connected.

## 8. Give it a task

Start `claude` in any directory. In your first message, say where the project is. Otherwise
the model looks in the current directory, finds nothing, and asks you. For example:

```
The project is in the workspace, reached by the loa-workspace tools, not in the local
directory. Find out what the tests cover and add a test for the one function that has none.
Run the tests when you are done.
```

Replace the second sentence with your own task.

Here's what you'll see. The model first calls the `workspace` tool, which describes the
repository and what the tools can do. It reads and searches with `read`, `grep` and `glob`,
changes files with `edit` or `write`, and runs your tests with `shell`. If the tests take a
while, they keep running in the background and the model waits for them with
`process_wait`. Claude Code asks you to approve each tool the first time it's used, unless
you've already allowed it.

The changed files are in your repository, the `root` folder. Look there, or ask the model for
a `git_diff`.

## 9. Push

Say: "Commit your work with a message that says what you changed, then push."

The model calls `git_commit`, then `git_push`. The push goes from the repository's current
branch to the branch of the same name on your `remote`, and it never force-pushes. The
server hands the token to git for that one remote; the model never sees it. Open the
repository on GitHub to see the branch and the commit.

If the model has no `git_push` tool, check three things:

- the `git:` block from step 3 is in the configuration
- the token from step 4 is stored
- the server was restarted after either change (`launchctl kickstart -k gui/$(id -u)/run.loa.workspace`)

Then start a new Claude Code session, so it picks up the new list of tools.

## 10. When something goes wrong

- **Check the server's log first:** `~/Library/Logs/Workspace/workspace.err.log` on a Mac,
  `journalctl -u workspace` on Linux. It has one line per tool call, with the tool and the
  reason for any refusal. It never records arguments or headers.
- `workspace --help` and `workspace <command> --help` list each command's options and exit
  codes.
- [The server guide](serve.md) covers every configuration setting, both tokens and the git
  credential.
- [The install guide](install.md) covers installing, upgrading, and what a first start looks
  like.
