Install

In this tutorial you build sandcastle from its most recent version, give it the example configuration and put it up as a service of your user. At the end, sandcastle check says what is ready, and the next tutorial, Your first job, runs a job through it.

You need a Linux machine that meets Supported systems, with Go and Git, and an account at the Claude Console. Run every command as yourself, never as root.

1. Get the most recent version

A version is a tag that passed every test of the promise. Anything between tags is work in progress.

git clone https://github.com/gravataLonga/sandcastle.git
cd sandcastle
git checkout "$(git tag --list 'v*' --sort=-v:refname | head -n 1)"

2. Build the binary

CGO_ENABLED=0 go build -trimpath -o dist/sandcastle .
./dist/sandcastle version

The binary must be static (CGO_ENABLED=0): the same file goes into every image. version prints its build and the commit it came from.

3. Copy the example configuration

mkdir -p ~/.config/sandcastle/sources
cp examples/config.yaml ~/.config/sandcastle/
cp examples/sources/notes.yaml ~/.config/sandcastle/sources/

The example source, notes, runs on this machine in the next tutorial. Find this machine’s address in your network:

ip -4 -brief address

Say it is 192.168.1.20. Open ~/.config/sandcastle/sources/notes.yaml and put that address in internal:, keeping the port, as in internal: 192.168.1.20:8080. Every key is in config.yaml.

4. Set the two secrets

Create an API key for sandcastle in the Claude Console, in a workspace of its own with a spend limit. The spend limit is the only cap on what sandcastle can spend, so do not skip it. See The key.

Give the key to sandcastle. It asks for it without showing it:

./dist/sandcastle secret set claude

notes takes any token you choose. Make one up:

head -c 32 /dev/urandom | base64 | ./dist/sandcastle secret set notes

Each prints secret <name> set.

5. Install

./dist/sandcastle install

It says each step on a line of its own: the configuration is valid, the machine has what it needs, the four images are built, the binary is copied to ~/.local/bin/sandcastle, the units are written, lingering is on, sandcastle.target is restarted and the keep is ready. Then it runs sandcastle check.

If the configuration is wrong or the machine lacks something, install says what and changes nothing. Fix it and run install again.

6. Read the check

The last lines are the check’s. Every line should be ok or warn but one:

FAIL  source notes: notes cannot be reached: …

Nothing listens at that address yet. That is the next tutorial.

Make sure ~/.local/bin is on your PATH, so that sandcastle is the installed binary from now on. Then go on to Your first job.

Keyboard shortcuts