Beer Can Labs
Staff / Gatekeeper
Front desk

Gatekeeper

Head of Perimeter Security

Stands at every door of the factory. The Gatekeeper checks who is knocking, wakes a sleeping agent when a message arrives, and is the only way an agent reaches the outside world. Agents never carry real credentials; the Gatekeeper adds them on the way out.

Design rules
A1, A2, E1, E6, S1
Contracts offered
2
Key flows
4

On the job

  • Verifies a bearer token or an OIDC login and says who the caller is, with their roles
  • Holds the Discord connection so a sleeping agent can still be reached
  • Proxies every outbound agent call and injects the credential
  • Relays a refused wake, such as a budget block, back to the person

Not my job

  • Decide what a caller may do. That is the Bouncer.
  • Price or count anything. That is the Treasurer and the Executive.
  • Start compute. That is the Landlord.
Key product flows

What Gatekeeper does, step by step

Flow

Let a person or service in

Every request to the control plane starts here. The Gatekeeper authenticates and never authorizes.

  1. A request arrives at the load balancer with a service token or an OIDC login.

  2. packages/auth verifies the credential and returns a principal: an actor name and a list of roles. It cannot say what that principal may do.

  3. For people on Discord, an admin-set identity link maps the Discord user to a person. A caller with no link is refused with 403 before any compute starts.

  4. The route names one privilege. The Gatekeeper asks the Bouncer whether the principal’s roles hold it.

    Works with Bouncer· contractauthorize →Roles map to privileges in one table, owned by the Bouncer.

  5. The decision, allowed or refused, is written to the ledger.

    Works with Auditor· contractLedgerStore / verifyChain →Perimeter decisions are part of the audit trail.
Flow

Wake a sleeping agent from Discord

The agent is at zero compute. The ingress is not.

  1. A message lands on gatekeeper-ingress, which keeps the Discord socket open even when no agent is running.

  2. The ingress asks the Landlord to start a run for the agent.

    Works with Landlord· contractcreateRun and the run lifecycle →Starting compute is the Landlord’s job.

  3. The Landlord asks the Treasurer whether the agent is inside its budget. If not, the wake is refused with 402 and the ingress tells the person why.

    $Works with Treasurer· contractcheckStanding →The Treasurer decides standing; the Gatekeeper relays the refusal.

  4. The Landlord reports back through the ingress presence calls: starting, working, idle.

    Works with Landlord· contractGatekeeperIngress →onAgentStarting, onAgentWorking and onAgentIdle keep the person’s Discord status honest.
Flow

Carry an agent’s outbound call

The agent talks to a base URL on the egress. It never sees the real endpoint or key.

  1. The agent calls one of its route base URLs with its run token. The egress checks the token and the agent’s policy for that route.

  2. The egress asks the Bouncer whether this request must be held for a person’s approval.

    Works with Bouncer· contractcheckHold →The Bouncer owns the hold rules; the egress enforces the answer.

  3. The egress asks the Keymaster for the credential and adds it to the request.

    Works with Keymaster· contractKeymaster.checkout →The credential exists only on the wire, never in the agent.

  4. The call goes out. A ledger row records it, and a progress event shows it on the run.

    Works with Auditor· contractLedgerStore / verifyChain →

  5. Progress for the run is published for live viewing.

    Works with Inspector· contractcreateInspector →
Flow

Carry a model call

Same desk, special route. The handlers stay with the Gatekeeper because the run token, throttle and ledger meet the request there.

  1. The agent sends an OpenAI-format chat request to the egress model route.

  2. The egress asks the Treasurer whether the agent is in good standing before spending anything.

    $Works with Treasurer· contractcheckStanding →

  3. It asks the Executive whether this agent may use the model it named.

    Works with Executive· contractcheckModel / offeredModels →Allow-list, factory default, training exemption and a run’s pin.

  4. The Executive serves the call and returns the result, a refusal, or the upstream failure.

    Works with Executive· contractcomplete →

  5. The usage is priced and the cost is recorded with the ledger row.

    $Works with Treasurer· contractcostUsd / priceFor →

Contracts Gatekeeper keeps 2 offered