Network and MCP access history
Access history answers two questions: which destinations a managed workspace or MCP session tried to use, and which attempts its policy allowed or denied. It records metadata on the server, without requiring an open TUI or browser.
Open Events and choose Audit, Network or MCP. Access views group records by Project, repository and session, retaining a separate shared-workspace scope wherever an exact session is unknown. History pages and address summaries load only when requested.
This is separate from the Events journal, which records controller operations such as grants, approvals and session creation. Neither journal is a transcript of shell commands, SQL statements or network packets.
Scope and attribution
Filter by Project group, repository, workspace or session. In the API,
projectId identifies a repository and groupId its optional Project group.
Ownership is resolved by the controller from the authenticated execution host
and existing workspace/session records, rather than accepted from a log entry.
Application users see only their own history; a session MCP tool cannot select
another tenant or repository.
| Record | What is identified | Boundary |
|---|---|---|
| Network | HTTP target hostname/port; HTTPS CONNECT target and TLS SNI admission | Requests that reach the managed egress proxy |
| Workspace source | Traffic from the Project container's observed Docker endpoint | Shared by its sessions and other processes |
| DinD source | Traffic from the Docker-in-Docker sidecar's observed outer endpoint | May include the daemon and nested workloads |
| MCP | Catalog server ID, protocol method and tool name when available | Calls through the managed session broker or built-in tools |
The host publishes the actual Docker endpoint map. The proxy does not trust an
agent-supplied source/session header. Endpoint observations expire after 15
seconds; missing or stale mappings produce unknown instead of guessing. This
distinguishes network origins, not individual processes.
Network traffic in a shared container has attribution: workspace-shared and no
session ID. A session view can include this explicitly labeled shared traffic,
but it does not mean that session made each request. MCP calls have an exact
session identity derived from the authenticated broker context. No network call
is attributed to whichever session happens to be visible or active.
Admission and execution are different
Each attempt has one policy decision and one execution outcome:
| Decision | Outcome | Meaning |
|---|---|---|
allowed |
forwarded |
Policy admitted the request and it was forwarded |
allowed |
upstream-error |
Policy admitted it, but transport or the upstream failed |
denied |
policy-denied |
The policy rejected it before forwarding |
denied |
rate-limited |
An MCP call exceeded its admitted call budget |
A remote HTTP 401/403 is not a devctrl policy denial. The HTTPS proxy does not decrypt traffic and cannot report encrypted application response codes. HTTP CONNECT success is recorded only after the required SNI check and upstream connection. A later SNI rejection is one denied attempt, never an allowed and a denied attempt. CONNECT-to-HTTP and its inner request are not counted twice.
The address summary is calculated on the controller. Each unique network hostname/protocol/port has total, allowed, denied and upstream-error counts plus first/last observed times. MCP summaries distinguish server, method and tool. Upstream errors are part of the allowed count, not a third policy category. Counts describe the retained, selected records, not lifetime traffic or bytes.
DinD uses the workspace boundary
On enforced workspaces the Project container and rootless DinD sidecar use the same isolated outer network. Only the policy proxy has an outbound network. The runtime verifies the sidecar's actual network attachment, closed external DNS and effective managed proxy environment. A second outer network or changed proxy environment is not silently accepted as compliant.
The DinD daemon receives proxy variables for registry operations. Nested HTTP
clients also need proxy variables when they need public Internet access. Inner
--network host, direct IP connections or clearing proxy variables do not create
an outbound route through the isolated outer network. Internal Docker networks
and services can still communicate normally.
See workspace Internet access for prerequisites and the existing network policy/template interface. Rootless Docker 29.9.1+ passes the same enforced boundary; older rootless daemons fail closed. Provider-native sandbox networks are outside this enforcement implementation.
Coverage and privacy
Recorded fields are a stable attempt ID, server cursor, timestamps, known scope, source/attribution, hostname or MCP server ID, port/protocol, method/tool, decision, outcome and a bounded reason category. MCP response duration is included when a correlated response is observed.
The producers do not record URL paths, queries, fragments, credentials, request
headers, bodies, prompts, TLS payloads, MCP arguments or MCP results. HTTPS
records show CONNECT, not an invented decrypted HTTP method. Custom methods
and reason strings cannot inject arbitrary diagnostic payloads into the journal.
Important limits:
- Direct TCP/UDP/DNS attempts blocked by the isolated network do not reach the proxy and therefore do not appear as proxy-denied records.
- Fixed-target Service traffic, internal peers, host-side external tools and provider-executed remote actions are not automatically network-proxy history. Managed MCP calls are recorded separately; this does not reveal their full downstream network activity.
- Legacy gateways without structured access-audit support are not backfilled. An explicit rebuild/upgrade is required. Updating a client does not recreate live Project containers or replace their running proxy.
- No records can mean unsupported capture, offline delivery or no observed requests. It is not evidence of zero network activity.
- Capture and delivery are bounded. The proxy bounds stdout buffering; the host reads at most 512 recent gateway records per pass, deduplicates IDs and keeps a maximum of 1,000 pending records. A sustained burst or long outage can lose older records. Dropped-count diagnostics do not contain destination payloads.
This is operational visibility, not a complete packet capture, immutable compliance archive or proof of every action an agent performed.
Loading, retention and export
The console does not download history with its normal state snapshot. History and unique-address summaries use separate bounded requests. Pages default to 100 records, with a server maximum of 500. Summary counts are aggregated on the controller rather than reconstructed from a full client-side download.
Access records reuse Settings → History cleanup → Audit events, including its enabled state, retention days, retained-record budget and cleanup interval. Defaults are 90 days, 100,000 records and a 60-minute interval. The access journal also enforces the configured record cap during ingestion while automatic cleanup is enabled. Disabling automatic cleanup disables both age and count cleanup; an administrator must monitor growth or run manual cleanup in that mode. It has no second, conflicting retention setting. Retention removes access metadata, not conversations, workspace files or containers.
Host delivery runs independently of the UI, in sequential batches of at most 100 records with a bounded retry outbox. Records whose workspace or session was deleted before delivery are acknowledged as discarded, with a host diagnostic; they cannot block newer records or be assigned to a replacement session. The controller deduplicates repeated host attempt IDs. It never needs an agent to repeat an operation to retry its history delivery. History responses negotiate the existing HTTP Brotli/gzip compression for eligible responses of at least 1,024 bytes. Small responses may remain uncompressed; binary or WebSocket transport is a separate negotiation.
Authenticated HTTP endpoints:
| Endpoint | Result |
|---|---|
GET /v1/access-attempts/page |
{attempts, nextCursor, through} |
GET /v1/access-attempts/summary |
{addresses, nextCursor, through} |
GET /v1/access-attempts/export |
Streamed JSONL with a fixed upper watermark |
Common filters include kind=network|mcp, groupId, projectId, workspaceId,
sessionId, source, decision, address, method and tool. Session reads
can explicitly request includeWorkspaceShared=true; the controller verifies
the session's workspace. Policy authorization is checked independently from
these filters.
Use numeric before for older history pages or after for forward collection.
Reuse through to pin a bounded snapshot while paging. Summary pagination uses
its opaque nextCursor with the same filter scope; do not construct or alter
that token. Export reads batches rather than accumulating the whole history in
browser or controller memory. Export important records before reducing
retention; removed records cannot be recovered through a later stream.
External live collectors
GET /v1/access-attempts/stream upgrades to an authenticated WebSocket. Use the
same owner-scoped filters and a persisted after cursor. Settings under
Log streaming are shared with Events: enabled state, polling interval,
batch size and heartbeat. Disabling that feed does not stop recording or HTTP
export. This is an inbound collector feed, not an outbound destination service.
Frames use these types:
{"type":"access.ready","cursor":1000,"latestCursor":1050}
{"type":"access.attempt","attempt":{"cursor":1001,"id":"attempt-example","kind":"network","address":"registry.example","decision":"allowed","outcome":"forwarded"}}
{"type":"access.cursor","cursor":1050}
{"type":"access.heartbeat","cursor":1050}
The attempt above is an abbreviated record; the actual frame includes its
authorized scope, timestamps and other available metadata. Forward only its
attempt object to a JSONL sink. Persist an attempt's server cursor after the
destination has durably accepted it. Reconnect with after=<saved-cursor> and
deduplicate by controller identity plus cursor. A cursor/heartbeat frame alone
does not prove the destination accepted a record.
Streams catch up in bounded batches and enforce backpressure. A slow collector
is disconnected instead of retaining an unlimited queue; it can resume using
its last durable cursor while the history is retained. Authentication and scope
are checked on connection and during polling, including expiry/revocation.
Negotiated WebSocket permessage-deflate compresses frames; HTTP Brotli/gzip
does not automatically compress WebSocket traffic. At-least-once replay is
supported; exactly-once delivery into an external system is not promised.
The ready frame also includes the earliest and latest retained scoped cursors
and timestamps in retained. Retention and bounded source buffers can create
gaps; a reconnect cannot recover records that are no longer retained.
MCP and troubleshooting
Session MCP exposes list_access_attempts and get_access_summary. They derive
the current repository/session scope from authenticated session identity; they
do not accept arbitrary tenant selectors. Use bounded filters to distinguish a
policy denial, an upstream failure and unavailable capture before requesting
new permissions. A history read does not grant access, fix a route or broaden
an upstream credential.
Operator MCP discovers the same authenticated HTTP operations through
controller_operations and calls paged JSON reads with controller_request.
Use native JSONL export or an external collector for larger history, rather
than placing it into one MCP response. Do not request secret files or log raw
tool arguments to diagnose an access failure.