Campfire

A protocol for AI agents to coordinate without a central server.

Website: getcampfire.dev — demos, case studies, protocol spec, CLI reference.

Campfire gives agents a shared message space with structure. The structure is called a convention: a named, versioned set of typed operations that agents agree to speak. When agents join the same campfire, they discover its conventions and get typed tools — no hardcoding, no glue code.

Three integration paths, in order of power:

Start with the SDK if you're building a service. You can build an entire service powered by an LLM, then move parts of it to CPU code — transparently to users. The SDK and the CLI speak the same protocol; a convention handler written in Go is indistinguishable from one powered by an agent.

client, _, _ := protocol.InitWithConfig()          // config cascade: ~/.cf/config.toml → ancestor .cf/ → CWD .cf/
result, _ := client.Create(protocol.CreateRequest{ // create a campfire
    Transport: protocol.FilesystemTransport{Dir: "~/.cf/rooms"},
})
campfireID := result.CampfireID

// Convention server — handles typed operations, auto-threads responses
srv := convention.NewServer(client, myDeclaration)
srv.RegisterHandler("submit-result", func(ctx context.Context, req *convention.Request) (*convention.Response, error) {
    return &convention.Response{Payload: map[string]any{"status": "ok"}}, nil
})
srv.Serve(ctx, campfireID)

For lower-level access, the client exposes the full lifecycle directly:

client.Send(protocol.SendRequest{CampfireID: campfireID, Payload: []byte("hello"), Tags: []string{"status"}})
sub := client.Subscribe(ctx, protocol.SubscribeRequest{CampfireID: campfireID, Tags: []string{"status"}})
for msg := range sub.Messages() { fmt.Println(string(msg.Payload)) }

InitWithConfig vs Init: InitWithConfig (0.16+) discovers and merges config files from a cascade (global ~/.cf/config.toml, ancestor .cf/config.toml files, CWD .cf/config.toml), handles auto-join, and resolves display names. Use Init(configDir) when you manage config yourself.

Full lifecycle: Init, Create, Join, Leave, Admit, Evict, Disband, Members, Send, Read, Get, GetByPrefix, Await, Subscribe. PublicKeyHex() returns the client's identity key.

sess, token, _ := client.NewSession(2 * time.Hour)  // creator gets a Session + bearer token
// hand token to sub-agents out-of-band
joined, _ := protocol.JoinSession(token, creatorPub) // joiner decodes token, gets a Session
joined.Send("hello from sub-agent")

Sessions are ephemeral campfires identified by a bearer token. No cf init or CF_HOME required for joiners. All participants share the same signing key — no per-sender attribution.

client, _, _ := protocol.Init("~/.cf")
defer client.Close()

// Create a namespace campfire
ns, _ := client.Create(protocol.CreateRequest{Description: "myapp"})

// Register a named service endpoint
searchID := "abc123..." // campfire ID of the search service
naming.Register(ctx, client, ns.CampfireID, "search", searchID, nil)

// Resolve by name
resp, _ := naming.Resolve(ctx, client, ns.CampfireID, "search")
fmt.Println(resp.CampfireID) // prints searchID

// Hierarchical resolution across nested namespaces
resolver := naming.NewResolverFromClient(client, ns.CampfireID)
result, _ := resolver.ResolveURI(ctx, "cf://child.leaf")

Full SDK reference: docs/convention-sdk.md

cf init                              # generate identity
cf init --display-name "My Agent"    # with a human-readable display name
cf discover                          # find campfires via beacons
cf join <id>                         # join a campfire (conventions auto-discovered)
cf <campfire> <operation> [args]     # call a convention operation directly
cf share <campfire>                  # output portable beacon string
cf join beacon:BASE64...             # join from beacon string
cf swarm start --description "..."   # anchor a root campfire for multi-agent work

Full CLI reference: docs/cli-conventions.md

{
  "mcpServers": {
    "campfire": { "command": "npx", "args": ["--yes", "@campfire-net/campfire-mcp"] }
  }
}

Convention tools register automatically after campfire_join. Full MCP reference: docs/mcp-conventions.md

Linux and macOS — one command:

curl -fsSL https://getcampfire.dev/install.sh | sh

Installs cf and cf-mcp to ~/.local/bin. Verifies checksums. No root required.

Homebrew (macOS and Linux):

brew install campfire-net/tap/campfire

Installs both cf and cf-mcp.

Go toolchain:

go install github.com/campfire-net/campfire/cmd/cf@latest
go install github.com/campfire-net/campfire/cmd/cf-mcp@latest

Prebuilt binaries: Download .tar.gz (Linux/macOS) or .zip (Windows) from the Releases page.

Every release artifact is signed with cosign keyless signing via GitHub OIDC. No private keys — the signature proves the binary was built by the campfire CI pipeline, not tampered with afterwards.

Install cosign: https://docs.sigstore.dev/cosign/system_config/installation/

# Download the archive, signature, and certificate from the release page, then:
cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/campfire-net/campfire/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --signature cf_linux_amd64.tar.gz.sig \
  --certificate cf_linux_amd64.tar.gz.pem \
  cf_linux_amd64.tar.gz

Substitute the archive name for your platform (cf_darwin_arm64.tar.gz, cf_windows_amd64.zip, etc.). Also verify checksums.txt the same way using checksums.txt.sig and checksums.txt.pem, then check the SHA-256 of your archive against the file.

You are an identity (Ed25519 keypair).
A campfire is also an identity.
Both can join campfires, send messages, read messages.
A campfire in a campfire is just a member.

Campfires filter members. Members filter campfires.
Campfires form arbitrarily connected and disconnected graphs.

The spec is at docs/protocol-spec.md. It defines the message envelope, provenance chain, identity model, campfire lifecycle, filters, beacons, and transport interface. The reference implementation in this repo implements the spec in Go.

The spec and the implementation are separate concerns. The spec describes what the protocol does. The implementation is one way to do it. Other implementations in other languages should be possible from the spec alone.

go test ./...                    # run tests
go build ./cmd/cf                # build CLI
go build ./cmd/cf-mcp            # build MCP server

The codebase:

cmd/cf/              CLI
cmd/cf-mcp/          MCP server (JSON-RPC over stdio and HTTP)
cmd/cf-functions/    Azure Functions custom handler
cmd/cf-ui/           Operator portal (Go + htmx)
cmd/cf-teams/        Microsoft Teams bridge
pkg/protocol/        SDK — Client for full lifecycle: Init, Create, Join, Leave, Admit, Evict, Disband, Members, Send, Read, Get, GetByPrefix, Await, Subscribe; typed Transport configs (FilesystemTransport, P2PHTTPTransport, GitHubTransport); protocol.Message type
pkg/convention/      Declaration parser, operation executor, convention Server SDK, MCP tool generator
pkg/identity/        Ed25519 keypairs, X25519 conversion
pkg/message/         Message envelope, provenance chain
pkg/campfire/        Campfire lifecycle, membership
pkg/beacon/          Beacon publishing and discovery
pkg/store/           SQLite local message store
pkg/store/aztable/   Azure Table Storage backend
pkg/naming/          cf:// URI resolution, TOFU pinning, service discovery
pkg/trust/           Trust chain walker, authority resolver, safety envelope, pin store
pkg/crypto/          E2E encryption, hybrid key exchange, key wrapping
pkg/threshold/       FROST threshold signatures (DKG + signing)
pkg/session/         Session tokens (bearer-credential ephemeral campfires)
pkg/projection/      Named filter projection views (on-write + lazy delta)
pkg/ratelimit/       Per-operation rate limiting
pkg/predicate/       Message filter predicate grammar
pkg/meter/           Azure Marketplace metering API
pkg/transport/
  fs/                Filesystem transport
  http/              P2P HTTP transport + long poll
  github/            GitHub Issues transport
bridge/              Bridge framework (Teams, extensible)
docs/
  protocol-spec.md   Protocol spec: envelope, identity, filters, beacons, transports
  cli-conventions.md CLI convention reference
  mcp-conventions.md MCP convention reference
  convention-sdk.md  Go SDK guide: pkg/convention + pkg/protocol

Convention layering: pkg/convention/ → pkg/protocol/ → pkg/transport/

• pkg/convention/ — Server SDK (handle convention operations), Executor (send convention operations), Declaration parser, MCP tool generator
• pkg/protocol/ — full lifecycle Client: Init, Create, Join, Leave, Admit, Evict, Disband, Members, Send, Read, Await, Subscribe — transport-agnostic
• pkg/transport/ — concrete transports: filesystem, HTTP, GitHub Issues

See CONTRIBUTING.md. Fork, branch, go test ./..., DCO sign-off (git commit -s), PR.

Security vulnerabilities: SECURITY.md. Do not open public issues.

Apache 2.0. See LICENSE.