Loa/Workspace
English
  • English
  • 简体中文
  • 日本語
  • Español

Getting started: from nothing to a pushed change

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

Coming soon: the download opens when the repository goes public.

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; 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. 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:

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 covers every configuration setting, both tokens and the git credential.
  • The install guide covers installing, upgrading, and what a first start looks like.