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:

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.