gapi

module
v0.1.0-proto2l Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 7, 2026 License: MPL-2.0

README

GAPI (GoPPydae Agent Process Infrastructure)

GAPI is the single-node supervision kernel of the GoPPydae ecosystem: the mechanism for spawning, supervising, checkpointing and verifying agents on one machine. It ships as a library, embedded in process by orchestrators, plus a reference daemon and CLI.

The distributed orchestrator that embeds it is Goblin. Running Goblin does not require running gapid alongside it - the kernel is linked in.

What it does

  • Agent supervision - three runner types (Go, Python, timer) behind one lifecycle.Agent interface, with dependency-ordered start.
  • Provenance - BLAKE3 .b3 digests and Ed25519 .sig sidecars. supervisor.productionMode refuses to start anything unverified.
  • Checkpoint/restore - CRIU dump and restore of a running process (core/checkpoint), the mechanism Goblin's live migration moves.
  • Signal delivery - pidfd-based, guarded by a start epoch, so a signal aimed at a dead run cannot land on its replacement.
  • Resource limits - cgroups v2, rootless supported.
  • Socket activation - systemd-style LISTEN_FDS handoff. Stream sockets only: TCP and UNIX, never UDP.
  • QUIC transport - one listener, ALPN-routed, with a registry Goblin extends.
  • PID 1 - opt-in init mode: subreaper, early mounts, watchdog, ordered shutdown.
  • Dual ADK - Python and Go agents with identical semantics.

Quick start

nix develop -c mage build

This produces bin/gapid and bin/gapictl. They are not on PATH; run them by path, or mage install them into $GOPATH/bin.

Scaffold an agent. The default language is Go:

./bin/gapictl agent new my_service

./bin/gapictl agent new my_service --lang python

Run the supervisor and talk to it:

./bin/gapid

./bin/gapictl agent status

Cluster and lifecycle verbs are subcommands: it is gapictl agent status, not gapictl status.

A Python agent

# agents/python/services/hello.py.service
ID = "hello"
TYPE = "service"

import time


def start():
    print("Hello from GAPI!")
    while True:
        time.sleep(60)

No classes, no inheritance. Metadata is read with getattr on the imported module, so it must be a real assignment - a commented # TYPE = "timer" is silently ignored.

Documentation

  • Getting started - first agent, end to end
  • Installation - NixOS module, images, systemd
  • Configuration - every key and metadata field
  • Development - building and testing GAPI itself is documented in the goppydae-docs repository
  • Architecture and features - the kernel's target design, and an as-built account of what it does, are documented in the goppydae-docs repository
  • Agent development - writing agents (Python, Go)

Repository layout

gapi/
|-- cmd/gapid/            # supervisor daemon
|-- cmd/gapictl/          # control CLI
|-- core/                 # the kernel, embedded by orchestrators
|   |-- agentmgr/ lifecycle/ supervisor/
|   |-- checkpoint/ procsig/ cgroups/
|   |-- crypto/ transport/ eventbus/ config/
|   `-- pid1/ subreaper/ mounts/ watchdog/ shutdown/
|-- internal/             # not importable by consumers
|-- pkg/cli/              # gapictl commands
|-- adk/go/ adk/python/   # agent development kits
|-- proto/gapi/v1/        # schemas
|-- nix/                  # NixOS module, package, image generators, VM tests
`-- divergence.jsonl      # where design and code currently disagree

Development

nix develop -c mage doctor

nix develop -c mage test

nix develop -c mage testADK

mage test runs the Go suite only. The Python ADK needs its generated bindings, which are not committed:

nix develop -c mage python:build

License

Mozilla Public License 2.0 (MPL-2.0)

Directories

Path Synopsis
adk
go
go/agent
Package agent is the Go Agent Development Kit runtime.
 Package agent is the Go Agent Development Kit runtime.
cmd
gapictl command
gapid command
core
adkpath
Package adkpath locates the Python ADK on the system it is running on.
 Package adkpath locates the Python ADK on the system it is running on.
agentmgr
cgroups
checkpoint
Package checkpoint dumps and restores process trees with CRIU (GOBLIN-DIV-018, research section 4.4/4.5).
 Package checkpoint dumps and restores process trees with CRIU (GOBLIN-DIV-018, research section 4.4/4.5).
client
clock
config
crypto
eventbus
lifecycle
logging
Package logging is the one place log handlers are built.
 Package logging is the one place log handlers are built.
metrics
mounts
Package mounts bootstraps the virtual filesystem hierarchy during Phase 0 of a PID-1 boot (GAPI-DIV-027), before cgroups or the event bus exist.
 Package mounts bootstraps the virtual filesystem hierarchy during Phase 0 of a PID-1 boot (GAPI-DIV-027), before cgroups or the event bus exist.
pid1
Package pid1 installs the explicit PID-1 signal semantics (GAPI-DIV-027).
 Package pid1 installs the explicit PID-1 signal semantics (GAPI-DIV-027).
procsig
Package procsig delivers signals to agent processes guarded by their start epoch (DDR-5, GAPI-DIV-016): a signal aimed at a dead process whose PID was recycled must never hit the new occupant.
 Package procsig delivers signals to agent processes guarded by their start epoch (DDR-5, GAPI-DIV-016): a signal aimed at a dead process whose PID was recycled must never hit the new occupant.
product
Package product carries the identity of the product whose process the kernel is running inside.
 Package product carries the identity of the product whose process the kernel is running inside.
schema
shutdown
Package shutdown is the PID-1 teardown executor (GAPI-DIV-027): a correct init shutdown is StopAll -> sync -> reverse umount -> reboot(2), replacing the naive grace + SIGKILL pattern.
 Package shutdown is the PID-1 teardown executor (GAPI-DIV-027): a correct init shutdown is StopAll -> sync -> reverse umount -> reboot(2), replacing the naive grace + SIGKILL pattern.
state
store
subreaper
Package subreaper implements the PID-1 orphan-reaping obligation (GAPI-DIV-027): the supervisor registers as a child subreaper so orphaned descendants reparent to it instead of pid 1, and a reap loop collects their exit statuses - zombie accumulation is a kernel obligation, not an optimization.
 Package subreaper implements the PID-1 orphan-reaping obligation (GAPI-DIV-027): the supervisor registers as a child subreaper so orphaned descendants reparent to it instead of pid 1, and a reap loop collects their exit statuses - zombie accumulation is a kernel obligation, not an optimization.
supervisor
transport
tui
version
watchdog
Package watchdog keeps a hardware (or software) watchdog timer fed (GAPI-DIV-027): if the supervisor hangs, the kicks stop and the device resets the machine.
 Package watchdog keeps a hardware (or software) watchdog timer fed (GAPI-DIV-027): if the supervisor hangs, the kicks stop and the device resets the machine.
examples
standalone command
internal
agentreg
db
db/graphdb
db/hybriddb
db/kvdb
ident
Package ident mints the UUIDv7 identifiers used for kernel events, lifecycle runs, and capability tokens (operator decision 2026-07-28: all ids are UUIDv7 where reasonable).
 Package ident mints the UUIDv7 identifiers used for kernel events, lifecycle runs, and capability tokens (operator decision 2026-07-28: all ids are UUIDv7 where reasonable).
logattr
Package logattr holds gapi's typed log attribute constructors: each pins one key to one value type, so a dropped value, swapped pair, or wrong type is a compile error instead of a quietly wrong JSON field (go-manifesto section 8).
 Package logattr holds gapi's typed log attribute constructors: each pins one key to one value type, so a dropped value, swapped pair, or wrong type is a compile error instead of a quietly wrong JSON field (go-manifesto section 8).
safeio
Package safeio centralizes every variable-path file open in gapi.
 Package safeio centralizes every variable-path file open in gapi.
statewatch
toposort
Package toposort is the one dependency-ordering implementation shared by the agent registry and the agent manager (review R5: centralize; R14: soft-dependency semantics).
 Package toposort is the one dependency-ordering implementation shared by the agent registry and the agent manager (review R5: centralize; R14: soft-dependency semantics).
pkg
cli
docsgen
Package docsgen renders reference documentation from the things that define it: the cobra command trees, and the configuration schema.
 Package docsgen renders reference documentation from the things that define it: the cobra command trees, and the configuration schema.
proto
test
adk
adk/fixtures/go command
adk/fixtures/go/capabilities_agent command
Capabilities agent with capability detection
 Capabilities agent with capability detection
adk/fixtures/go/hash_agent command
Hash agent for testing schema hashing
 Hash agent for testing schema hashing
adk/fixtures/go/lifecycle_agent command
Lifecycle agent demonstrating full lifecycle support
 Lifecycle agent demonstrating full lifecycle support
adk/fixtures/go/simple_service command
Simple service agent for cross-ADK testing
 Simple service agent for cross-ADK testing
pid1/fixtures/orphanmaker command
Orphanmaker is the PID-1 e2e fixture agent: on start it double-forks so a grandchild is orphaned onto the container's init (gapid), which must reap it - the kernel obligation the harness asserts.
 Orphanmaker is the PID-1 e2e fixture agent: on start it double-forks so a grandchild is orphaned onto the container's init (gapid), which must reap it - the kernel obligation the harness asserts.
tools
gendocs command
Command gendocs renders gapi's reference documentation.
 Command gendocs renders gapi's reference documentation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.