Skip to content

📖 docs: clarify first-run and integration guidance #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
clubanderson merged 1 commit into from
Oct 29, 2026
Merged

📖 docs: clarify first-run and integration guidance #44

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,18 @@ tar xzf crux_0.1.0_linux_amd64.tar.gz
./crux --version
```

That archive example is for Linux on amd64. On macOS choose `darwin_arm64`
for Apple Silicon or `darwin_amd64` for Intel from the same release. Keep the
signature-verification command unchanged. macOS includes `shasum`, so verify
the selected archive against its signed checksum before extracting it:

```sh
# Apple Silicon example; use darwin_amd64 in both places on Intel
grep 'crux_0.1.0_darwin_arm64.tar.gz$' checksums.txt | shasum -a 256 -c -
tar xzf crux_0.1.0_darwin_arm64.tar.gz
./crux --version
```

The container image is signed the same way:

```sh
Expand Down Expand Up @@ -115,6 +127,12 @@ crux kick scout "look at issue 42" # send it work
crux stop scout # stop it
```

While `crux run` is still active, `crux ps` should list `scout`; `crux logs
scout -n 50` should show the agent's startup or prompt. Output varies by
backend. If startup fails, check `command -v tmux` and `command -v copilot`,
then run and authenticate the agent CLI directly before retrying. Do not send
the example issue task until you have a repository and task you intend it to work on.

Agent files live under `--workdir` (default `$HIVE_WORK_DIR`, then
`$HOME/.crux`). While `crux run` is in the foreground it opens a small
control socket in that folder, and `ps`, `logs`, `kick` and `stop` use it
Expand All @@ -125,6 +143,11 @@ to reach the live agent.
`crux serve` keeps the runtime up and exposes it over HTTP+JSON, so other
programs (or you, from another shell) can drive it:

The example assumes `/run/crux` already exists and is writable by the service
user; it is not normally writable by an ordinary macOS or Linux user.
For a local trial, use a socket path in a private directory you own instead
and set `CRUX_SERVER` to that same path. Do not make a shared socket world-writable.

```sh
# Serve on a unix socket. A unix socket is a file on disk that two
# programs on the same machine use to talk to each other.
Expand Down Expand Up @@ -204,6 +227,14 @@ The design record is

## What crux exposes

**Go integrator reference starts here.** If you only want to operate agents,
the [commands](#commands), [service setup](#run-it-as-a-service), and
[runbooks](runbooks/README.md) are enough. The remaining interfaces and routes
are for programs embedding or calling Crux.

<details>
<summary>Advanced: Go interfaces, HTTP routes, host callbacks, and packages</summary>

Crux has three layers you can build on. Each one is a Go package in this
repository. The first is the Go interface. The second is the same thing
over HTTP. The third is what crux asks the host for in return.
Expand Down Expand Up @@ -392,6 +423,8 @@ a refusal.
- `hivecap`: the runtime-side adapters for the hive callback.
- `serve`, `cli`, `cmd`: the HTTP server, the `crux` command, and the binary.

</details>

## Contributing

The Go code in this repository is not edited here. It is a copy of
Expand Down
Loading