Guides / For developers

For developers

This page is for two kinds of reader: someone reading or changing kosa8's source, and someone driving kosa8 from their own program. It covers how to build and test, what each package is for, the path a request takes through them, the service's HTTP API, and the rules the code is written to.

If you have not read How kosa8 works, start there. It explains the three programs and the boundary this page assumes.

Build

kosa8 is written in Go; go.mod names the version it needs (Go 1.26). Running sandboxes needs macOS on Apple silicon, or Linux with KVM, cloud-hypervisor and virtiofsd. Everything else, including the unit tests, builds anywhere Go does.

$ make build          # bin/kosa8 and bin/kosa8d
$ make guest          # build the guest image and install it to ~/.kosa8/guest
$ make test           # go test ./...
$ make test-race      # go test -race ./...
$ make lint           # go vet ./...
$ make cross          # build the guest helper and every package for Linux arm64 and amd64
$ make check          # fmt, lint, test and cross: everything CI enforces

make cross matters because the macOS build cannot see two things: the files tagged for Linux, and the guest helper, which is Linux-only. make fips builds against Go's FIPS 140-3 module and make test-fips runs the tests under it.

The source layout

Each package starts with a comment that says why it exists and what it deliberately does not do. Read that before the code.

The path of a request

From JavaScript and TypeScript

For Node programs there are two npm packages over this API, so you do not have to speak HTTP:

Choosing a path compares them with MCP and the Docker API.

The service's HTTP API

The service listens on a unix socket, ~/.kosa8/run/kosa8.sock. The socket's file permissions let only your user open it, and that is the whole of its access control: there is no token on it. It serves two trees.

Headers

Native routes an integrator needs

The full list is the table in pkg/apid/gate/routes.go, which the service will not start without.

Worked example: a sandbox behind a broker

This creates a sandbox whose only way out is its egress broker. The real API key goes in the request and stays with the service; the response gives you a placeholder to hand to the sandbox instead.

$ curl --unix-socket ~/.kosa8/run/kosa8.sock \
    -X POST http://localhost/kosa8/v1/sandboxes \
    -H 'Content-Type: application/json' \
    -d @- <<EOF
{
  "name": "review-1",
  "egress": "deny",
  "mounts": [
    {"host_path": "/Users/you/code/api", "guest_path": "/work", "read_only": true}
  ],
  "broker": {
    "allow": [
      {"host": "registry.npmjs.org"}
    ],
    "routes": [
      {"name": "anthropic",
       "upstream": "https://api.anthropic.com",
       "header": "x-api-key",
       "methods": ["POST"],
       "paths": ["/v1/messages"],
       "secret": "$ANTHROPIC_API_KEY"}
    ]
  }
}
EOF

The answer is 201 Created:

{
  "sandbox": {
    "id": "review-1",
    "name": "review-1",
    "state": "running",
    "egress": "deny",
    "broker": {
      "url": "http://192.168.127.254:57504",
      "hosts": ["registry.npmjs.org"],
      "routes": ["anthropic -> api.anthropic.com"]
    },
    …
  },
  "boot_ms": 653,
  "broker": {
    "url": "http://192.168.127.254:57504",
    "placeholders": {
      "anthropic": "kosa8-placeholder-1803c857986afe6bc9f59600e4d6f6f8"
    }
  }
}

Give the sandbox the stand-ins as environment variables when you run something in it. The proxy variables send everything else through the broker too:

$ curl --unix-socket ~/.kosa8/run/kosa8.sock \
    -X POST http://localhost/kosa8/v1/sandboxes/review-1/pull -d '{"ref": "node:22-alpine"}'
$ curl --unix-socket ~/.kosa8/run/kosa8.sock -N \
    -X POST http://localhost/kosa8/v1/sandboxes/review-1/run -d '{
  "image": "node:22-alpine",
  "args": ["sh", "-lc", "env | grep -c ANTHROPIC"],
  "env": [
    "ANTHROPIC_BASE_URL=http://192.168.127.254:57504/anthropic",
    "ANTHROPIC_API_KEY=kosa8-placeholder-1803c857986afe6bc9f59600e4d6f6f8",
    "HTTPS_PROXY=http://192.168.127.254:57504",
    "HTTP_PROXY=http://192.168.127.254:57504",
    "NO_PROXY=192.168.127.254"
  ]}'
$ curl --unix-socket ~/.kosa8/run/kosa8.sock \
    -X DELETE http://localhost/kosa8/v1/sandboxes/review-1

run answers with one JSON object per line: output frames with stream and base64 data, then a last frame with done and the exit status.

Driving the CLI instead

You do not have to speak HTTP. Every command takes --json and prints one JSON document with a stable shape in place of the table:

$ kosa8 sandbox ls --json
$ kosa8 audit ls --json -n 0
$ kosa8 agent kits --json

A failing command exits non-zero and says what to do next. --approval ID is the other global flag; it sends the X-Kosa8-Approval header for you.

Writing a new MCP tool

kosa8's own tools are registered in registerTools in pkg/mcpd/tools.go. Each is a thin, typed wrapper over the same service API the CLI uses, so an agent and a person see the same behaviour. A new tool is four things, and the build tells you if you forget the two that matter most.

type sandboxRunIn struct {
	Sandbox  string   `json:"sandbox" jsonschema:"sandbox name"`
	Image    string   `json:"image" jsonschema:"image to run inside the sandbox"`
	Command  []string `json:"command,omitempty" jsonschema:"command and arguments"`
	Approval string   `json:"approval,omitempty" jsonschema:"id of a recorded signed approval …"`
}

add("sandbox_run", "Run a container inside a sandbox's private engine, isolated from the host.", true,
	func(ctx context.Context, _ *mcp.CallToolRequest, in sandboxRunIn) (*mcp.CallToolResult, any, error) {
		s := s.with(in.Approval)
		out, exit, err := s.postStream("/kosa8/v1/sandboxes/"+url.PathEscape(in.Sandbox)+"/run",
			map[string]any{"image": in.Image, "args": in.Command})
		…
		return text(out), nil, nil
	})

panic: mcpd: tool NAME has no entry in toolFeature

panic: gate: route "PATTERN" has no entry in gate.Routes — say which approval kind it performs, or why it needs none

Two tests hold the tables to reality: TestEveryToolIsPriced in pkg/mcpd and TestEveryMutatingRouteIsClassified in pkg/apid.

The rules the code follows

The test layers

Fuzz targets

$ go test ./pkg/schema -fuzz FuzzEvaluate    # argument rules against arbitrary arguments
$ go test ./pkg/scorer -fuzz FuzzHeuristic   # the deterministic veto in front of the scorer

Both take input an agent or a third-party server controls, which is why they are the ones fuzzed.

Further reading in the repository

The design notes in docs/design/ say why each subsystem is the way it is, and what it does not do. They are in the source tree, not on this site.

Where to go next