Contribute

Coding agent instructions

These instructions are for an AI coding agent that works in the Brig repository: Claude Code, Codex, Cursor, or any other tool that reads AGENTS.md. A change must meet these rules.

These instructions add no rules. Contributing and AI policy are the source. If these instructions disagree with the source, the source is correct. Then fix these instructions.

What Brig is #

Brig runs coding agents in a microVM sandbox.

Each package states its job in its // Package comment. Before you change a package, read that comment.

docs/README.md is the map of the documentation.

The two promises #

Brig makes two promises. A change that weakens either promise is a bug, even when every test passes.

1. The guest reaches only the host directories Brig names for it. Brig handles paths that the guest can influence through an os.Root, never by joining strings (see internal/wrap/rootio.go).
2. The guest gets only the credentials you name for it. Brig forwards values by name, never in argv, and never writes them into the guest home.

Security lists the limits of both promises.

If a change moves either promise, you must do the two steps in Contributing.

Dependency rules #

Brig enforces some of these guarantees as dependency rules. internal/hostsrc/arch_test.go fails if the run path can reach the host credential importer.

If a test of this type fails, the design does not permit the change. Do not work around the test.

Negative tests #

A negative test is worth more than a positive one. Contributing gives examples.

Checks before done #

Before you call a change done, run what CI runs. CI does not call make, so make all is not the full set of checks.

gofmt -l .
go vet ./...
go test -race ./...
script/smoke.sh

gofmt -l . must print nothing.

script/smoke.sh runs anywhere and needs no VM.

For a documentation change, also run:

script/check-retired-spellings.sh

It fails a doc that teaches a command spelling scheduled for removal. Migration lists the current spellings.

Limits of local gates #

• The real runtime. The smoke test stubs hull (macOS) and nerdctl (Linux). A change to how Brig invokes either runtime can pass every local check and still be wrong.
• The keychain. On macOS, the tests in internal/secret use the real login keychain. See Contributing.

For a change to the run, exec or credential path, say in the pull request whether a real brig run exercised it. Do not claim that you did if you did not.

Kept tests #

script/check-tests-kept.sh fails CI when a test name disappears.

Do not delete or rename a test to make a change pass.

If you intend a rename:

1. Say why in the pull request.
2. Ask a maintainer for the removes-tests label.

Dependencies #

Brig has three direct dependencies. Contributing lists them.

Do not add a module to go.mod unless the pull request says why the standard library or a subprocess will not do.

Commits and pull requests #

You must obey the rules in Contributing:

• Commits: the Conventional Commits format, the trailers and the sign-off.
• Pull requests and review: one logical change, the template and the draft.

Scope and honesty #

These rules come from AI policy:

• Keep changes small and bounded. A large mechanical rewrite or a speculative fix costs a maintainer more to review than it saves.
• Report what happened. Do not state that tests passed, a bug reproduced or a behaviour was verified unless it did.
• Match the code around you. Comments in this repository explain why the code is the way it is, often with the failure it prevents. Keep those comments when you edit. Write new comments the same way.
• Do not open a public issue or pull request for a vulnerability. Follow the Security policy.