FICCDocumentation
nightly prerelease / Version 0.3.0.dev1Project website
Reference library
Reference
On this page
  1. Authentication
  2. Controller and job routes
  3. File routes
  4. Terminal routes
  5. Agent and bus routes
  6. Module and workspace routes
  7. Provider actions and displays
  8. Runtime policy administration
  9. Inference and models
  10. Cluster federation

Local API#

The browser and CLI use the same authenticated HTTP API. Local mode binds the configured port on 127.0.0.1. Remote mode binds a protected Unix socket behind the configured HTTPS gateway. Arbitrary proxy headers and CORS do not grant access. Owner CLI requests remain local.

Authentication#

Browser login exchanges a single-use bootstrap credential for an HttpOnly, SameSite=Strict cookie. Obtain that credential through ficc open. The URL fragment is removed before the browser sends the login request. Do not save that URL in a log or share it with another person.

Browser mutations require the session's X-CSRF-Token value and allowed Origin. API clients use Authorization: Bearer TOKEN. Read tokens from protected files or stdin. Do not expose them in process arguments. Each request checks expiry, current grants and node/root scope.

Credentials also name a durable user and selected project. Current membership limits their original scopes. Session responses include the public identity and project records. Browser requests send X-FICC-Project and X-FICC-Session; an outdated window receives 409 project_changed or 409 session_changed. These headers supplement authentication and do not grant access.

Session responses also include expires_at as Unix seconds and the remote mode flag. Remote cookies use the __Host-ficc_session name with Secure and HttpOnly attributes. External access tokens are not FICC bearer credentials. GET /api/v1/login reports remote identity readiness without requiring a login. POST /auth/start requires the exact configured origin. GET /auth/callback consumes browser-bound one-use state. Only this callback permits cross-site navigation. Normal origin and CSRF checks remain in force elsewhere.

Owner-only GET /api/v1/external-identities lists approvals and provider status. PUT /api/v1/external-identities accepts issuer, external_subject, subject_id, disabled and revision. Revision zero creates a mapping. Later edits require its current revision. Mapping the local recovery owner is refused.

GET /api/v1/projects lists the caller's projects. POST /api/v1/session/project accepts project_id and rotates a browser session without extending its expiry. Bearer tokens cannot switch projects. Owner identity administration uses GET/POST /api/v1/identities, POST /api/v1/projects, and PUT /api/v1/identities/{id} or /api/v1/projects/{id} with label, disabled and revision. GET /api/v1/projects/{id}/members lists memberships; PUT /api/v1/projects/{id}/members/{subject} accepts scopes and revision. These administration routes require identities:manage and local owner authority. Owner resource administration uses GET /api/v1/project-resource-options and GET/PUT /api/v1/projects/{id}/resources. The PUT body contains node_ids, root_ids and revision. It replaces the project selection. Remote folders require their machine assignment. Stale revisions return 409 revision_conflict. The permissions and session responses report effective machine and folder lists; project switching preserves the original credential limits separately. Job, file-operation, transfer and terminal responses include durable subject_id and project_id fields. Cross-project object access returns 404; lists include only the selected project. Terminals also require their subject, except for the local recovery owner within that project. See identities and projects for the current capability boundary.

Controller and job routes#

The separate agent observation endpoints provide an explicit disclosure permission, limited inventory fields and attributed observation access. They use the same authenticated identities, project resources and current policy checks.

Method and path Result
GET /api/v1/health Minimal service status; no authentication required
POST /api/v1/session Exchange a bootstrap credential for a browser session
GET /api/v1/session Current principal, mode, version and CSRF value
DELETE /api/v1/session Revoke the current session
GET /api/v1/nodes Machines permitted by the current credential
GET /api/v1/nodes/{id} One permitted machine and its current observation
GET /api/v1/nodes/{id}/resources Resource sample, timestamp and stale flag
POST /api/v1/nodes/refresh Refresh one to 64 distinct machine IDs
GET /api/v1/profiles Approved local SSH profiles
POST /api/v1/node-previews Resolve and verify an enrollment candidate
POST /api/v1/nodes Confirm a preview and any required helper installation
DELETE /api/v1/nodes/{id} Forget a local enrollment; does not uninstall remotely
GET /api/v1/permissions Effective scopes and node restriction
GET /api/v1/tokens Token metadata; never secret values
DELETE /api/v1/tokens/{id} Revoke a token
GET /api/v1/audit Bounded recent audit events
POST /api/v1/nodes/{id}/helper-upgrade Explicitly update the enrolled node helper
POST /api/v1/operation-previews Validate and freeze a managed-job request
POST /api/v1/operations Persist a previewed job batch; requires Idempotency-Key
GET /api/v1/operations Up to 200 visible operations, newest first
GET /api/v1/operations/{id} Per-machine states, limits and authoritative results
POST /api/v1/operations/{id}/cancel Record cancellation for selected node_ids and optional force
GET /api/v1/operations/{id}/logs/{node_id} Bounded base64 stdout/stderr chunk and byte cursor

The available scopes are nodes:read, nodes:write, resources:read, tokens:manage and audit:read, plus jobs:read, jobs:execute, jobs:cancel and jobs:logs. Files add files:read, files:write, files:mode and files:delete. Data sources add data:read, data:export, data:write and data:manage; see the source API and provider contract. Terminals add terminals:read, terminals:execute and terminals:stop. Existing credentials do not gain new scopes during an upgrade.

Sign in again as owner or issue an appropriate new token. Node lists filter inaccessible machines. Enrollment, profile inspection, token administration and global audit access require unrestricted node access as well as their operation scope.

Control requests have a 1 MiB limit. Invalid fields are rejected. Errors have this shape, with an appropriate HTTP status:

json
{"error":{"code":"denied","message":"This credential does not permit the action."}}

Resource values use bytes, seconds and percentages. Missing values are null or explicitly unavailable. A stale sample remains visible with its age. Do not treat an old sample as current capacity or a connection failure as zero use.

The helper response contract is node-v1.json. Generate it with python tools/export_schema.py schemas/node-v1.json. The current collector reports the root filesystem and cumulative network counters. GPU measurements use bounded nvidia-smi queries, AMDGPU sysfs/hwmon reads, or Apple Silicon ioreg driver statistics. Each GPU adds optional source, memory_kind and reservation_supported fields. Defaults accept older helper responses. New AMD and Apple records explicitly disable reservations; the CUDA UUID check still excludes older AMD records. Missing readings remain null. AMD observation IDs contain the node-local PCI address; Apple registry IDs are valid for the current boot. Neither identifies a CUDA reservation device. See GPU observations for sources, units and qualification limits.

See managed jobs for the typed request and lifetime rules. A job preview expires after 120 seconds and belongs to its credential. Submit {"preview_id":"ID"} with an Idempotency-Key of 16 to128 printable ASCII characters. Deduplication is credential-bound. A matching previously accepted request returns its original operation even after preview expiry. A conflicting request returns 409.

Log queries accept stream=stdout or stderr, nonnegative offset and limit 1..65536. They return data_base64, next_offset, total_bytes, dropped_bytes and complete. Cancellation accepts {"node_ids":["ID"],"force":false} and returns 202 with the current operation. Neither acceptance nor a transport error proves termination.

The service provides a development contract under /api/v1. Clients should check the returned application version. Additive and breaking changes are documented before a stable API release.

File routes#

Root registration uses the private owner CLI only. GET /api/v1/file-roots returns permitted root IDs and their available actions. POST /api/v1/files/list accepts root_id, opaque entry_id, optional cursor and limit up to 200. POST /api/v1/files/preview accepts root_id, entry_id and limit up to 65536.

POST /api/v1/file-operation-previews prepares mkdir, rename, mode or delete. POST /api/v1/file-operations accepts preview_id and confirm:true with an Idempotency-Key header. GET the collection or /{id} for per-entry outcomes. Previews expire after 120 seconds; accepted keys retain their original result. POST /{id}/reconcile checks durable receipts for an uncertain file operation.

POST /api/v1/transfer-previews prepares copy, upload or download, with sources, optional destination and an explicit overwrite choice. POST /api/v1/transfers accepts preview_id and confirm:true with Idempotency-Key. GET the collection or /{id} for progress. POST /{id}/resume takes item_ids; POST /{id}/cancel also takes discard_partial. Existing source entries use root_id and opaque entry_id. Upload source metadata uses name, size and last_modified.

PUT /api/v1/transfers/{id}/items/{item_id}/chunks?offset=N accepts at most 262144 binary bytes as application/octet-stream and X-Chunk-SHA256. POST the item's /finish endpoint verifies and publishes it. GET the /content endpoint serves a successfully prepared download attachment. See files for recovery, resource limits and the trusted-account boundary.

Terminal routes#

GET /api/v1/terminals lists permitted records. POST creates an intent with node_id, mode (ephemeral or tmux), label, cols, rows, confirm_execution:true and idempotency_key (16-80 ASCII letters, digits, hyphens or underscores). A matching key returns the same record; changed content returns 409. GET /{id} reads a record; POST /{id}/stop requires confirm_stop:true. POST /{id}/reconcile queries an uncertain tmux session's exact saved identity. It requires terminals:execute and never creates or attaches a session.

POST /api/v1/terminals/{id}/tickets returns ticket, expires_at and websocket_path. Connect to that path on the same origin and send {"type":"auth","ticket":"..."} as the first text frame. No ticket or credential belongs in the WebSocket URL. Binary frames carry raw input/output.

Text controls are {"type":"resize","cols":80,"rows":24} and {"type":"ack","bytes":1024}. ACK counts newly processed output bytes, not characters or socket receipt. The server sends {"type":"status","state":"attached"} and explicit exit/error states. See terminals for bounds, reattachment and grant semantics.

Agent and bus routes#

GET /api/v1/agent-profiles returns registered profiles visible under agents:read. Each profile includes current node metadata (id, name, account, host, SSH profile) for its enrolled machine. The profile and metadata share the caller's node restrictions and current policy; reading them does not require the separate node inventory grant. Owner-only profile registration uses the private local socket. The response also includes per-machine discovery status, last check time and bounded command-check errors. Automatic profiles include source:discovered, command, availability and a discovery_revision that invalidates a preview when its runtime changes.

POST /api/v1/agent-profiles/refresh polls the caller's permitted machines and returns the same inventory. It requires agents:read and never starts an agent. The response waits at most two seconds; scans still running report scanning. Read GET /api/v1/agent-profiles for subsequent results. Background discovery also runs without a browser. Repeated scans keep profile identities; commands missing from a successful scan become unavailable, while failed scans retain the last observed inventory. GET /api/v1/agents and /api/v1/agents/{id} return runtime, node, run and terminal identities, delivery capability, state and observed contact time.

POST /api/v1/agent-previews takes profile_id, label, run_id, cols and rows. It requires agents:execute and bus:send for the selected enrollment. POST /api/v1/agents takes preview_id, idempotency_key and confirm_execution:true. Repeated matching requests return the saved agent; an uncertain launch is never automatically repeated.

POST /{id}/stop requires agents:stop and confirm_stop:true. POST /{id}/reconcile uses agents:execute and queries the saved identity. POST /{id}/rebind requires agents:execute, runtime_session_id and confirm_rebind:true; the requested ID must equal the node's observed changed session. Attachment uses the ordinary terminal ticket route and terminal execution scope.

GET /api/v1/bus/runs requires bus:read. POST takes name and idempotency_key under bus:send. GET /{id}/messages takes optional after (nonnegative ordinal) and limit (1-100), returning messages and next_after (null when no further page exists). POST takes type, validated body, explicit recipient_ids (at most64), delivery (inbox or direct), optional reply_to, idempotency_key and confirm_delivery:true.

It returns a canonical message and separate deliveries. POST /{id}/close takes confirm_close:true and refuses unresolved deliveries or active agents. A restricted credential must cover every node enrolled in a run before viewing its shared message content.

GET /api/v1/bus/deliveries accepts optional run_id and returns the newest 1,000 visible receipts. Receipt states describe storage and inclusion layers, never work completion. Node replies bind sender identity and run from the saved launch record and use its original grant. No API endpoint accepts a host bus file path. See agents and bus for tooling, resource limits, revocation and explicit archival.

Agent records can include outbox_rejections, the latest 16 permanent reply refusals. Each summary contains id, code, detail (at most 240 characters), and rejected_at (Unix seconds). These are separate from bus delivery receipts and do not claim host storage. Exact rejected content remains in the node spool and is available through the registered local rejects and rejected tools.

Module and workspace routes#

Module management requires unrestricted local node and root access. The scopes are modules:read, modules:manage and modules:execute. Workspace access uses workspaces:read and workspaces:write; shared sound uses audio:playback. These caller scopes are separate from each installed archive's capability grants.

Method and path Request or result
GET /api/v1/modules Installed manifests, digests, activation and grants
GET /api/v1/modules/sandbox Current executable-module isolation prerequisites
GET /api/v1/module-targets Permitted capability targets and labels
GET /api/v1/supplied-modules Separate archives supplied with this installation
POST /api/v1/supplied-module-previews Inspect package_id from that catalog
POST /api/v1/module-install-previews Inspect raw local archive bytes, at most 16 MiB
POST /api/v1/module-fetch-previews Inspect url, optional expected_digest, allow_private_network and allow_http
POST /api/v1/modules Install preview_id, exact digest and accept_unverified:true
DELETE /api/v1/module-install-previews/{id} Release the caller's unused inspection
POST /api/v1/modules/{digest}/activation Set enabled and exact capability/target grants
DELETE /api/v1/modules/{digest} Remove a package after retained operations are cleared
POST /api/v1/module-invocations Invoke a declared action within a saved panel's target selection
GET, POST /api/v1/workspaces List workspaces or create one with name
GET, PUT, DELETE /api/v1/workspaces/{id} Read, update or delete a revision-checked workspace
PUT /api/v1/workspaces/{id}/instances/{instance}/state Save revision and bounded state
GET, PUT, DELETE /api/v1/workspaces/{id}/views/{view} Read, save or remove one panel layout
GET, PUT, DELETE /api/v1/workspace-surfaces/{surface} Read, save or remove one workspace tile layout
GET /api/v1/workspace-layouts Saved surfaces and views
GET, PUT /api/v1/audio/preferences Read or update revision, volume and muted
POST /api/v1/audio/leases Acquire playback for instance_id and surface_id
PUT, DELETE /api/v1/audio/leases/{id} Renew or release using the owning surface_id

Inspections expire after 300 seconds. Installation leaves the package disabled with no grants. Activation uses grants shaped as {"capability":"workspace:read","target_ids":["WORKSPACE_ID"]}. Each digest has its own grants. An update does not inherit another archive's authority.

An invocation supplies workspace_id, instance_id, action, targets and optional parameters. The host obtains the package digest from the saved panel; the request cannot substitute another digest. targets contains one to 64 distinct IDs within that panel's selection. See the protocol and component format for module-side contracts.

Workspace updates supply the current revision, name and complete instances list. Each instance has id, digest, title, optional state and selected targets. View saves use revision and layout; surface saves also include tiles. Delete requests supply revision as a query parameter. A stale revision returns 409. No save silently replaces another window's newer data.

The /api/v1/module-editor/ POST routes use workspace_id and instance_id. roots lists permitted roots; list uses root_id, opaque entry_id and optional cursor. read takes distinct items with those identities. save adds each file's sha256 and UTF-8 text, plus accept_retained_exchange:true.

It requires an Idempotency-Key and retains original or conflicting copies for explicit recovery. operations, status, recovery, cleanup and remove-receipt expose that history. See the editor workflow before removing retained copies.

Provider actions and displays#

VM actions use vm:read, vm:power and vm:console. Containers use container:read, container:logs and container:power. Administration uses admin:read, admin:logs, admin:services and admin:power. Current caller scopes and package grants must both permit each selected system and action.

GET /api/v1/vm-profiles lists libvirt connections. PUT or DELETE /api/v1/nodes/{id}/vm-profile changes one enrolled connection. PUT uses connection (system or session) and enabled. GET /api/v1/proxmox-profiles lists Proxmox connections. PUT /api/v1/nodes/{id}/proxmox-profile probes and saves enabled; DELETE removes the profile after receipt cleanup.

Packaged provider management requires providers:write on the selected endpoint. GET and POST /api/v1/adapter-profiles list profiles and create a disabled binding. POST uses digest, endpoint_kind, endpoint_id and transport_binding_id. POST /{profile_id}/grant adds expected_revision and confirm:true. POST /{profile_id}/revoke removes account access. DELETE /{profile_id} requires confirm:true and no retained receipts.

These suffixes are relative to /api/v1/adapter-profiles. GET /api/v1/adapter-bindings uses endpoint_kind and endpoint_id query parameters. POST registers an owner-selected socket_path for an enrolled Linux endpoint. Unavailable transports refuse registration or use.

GET and POST /api/v1/windows-endpoints list and register separate Windows endpoints. PUT and DELETE /{endpoint_id} require expected_revision; DELETE also requires confirm:true. POST /{endpoint_id}/activation uses expected_revision and enabled. Endpoint writes require unrestricted nodes:write. See Windows endpoint fields and trust.

Registration uses name, host, port, configuration, commands, certificate_sha256, ca_pem, credentials and optional vmconnect. Credentials contain username, password and domain. VMConnect has its own port, certificate digest and credentials. An update can omit credentials and CA data to preserve saved values; vmconnect:null removes the display connection.

GET, PUT and DELETE /api/v1/container-profiles manage container connections; DELETE adds /{profile_id}. Administration uses the same methods under /api/v1/admin-profiles. Its PUT body has node_id, manager (user or system), optional profile_id and enabled. Registration checks the existing remote account's authority; it does not obtain an elevated password.

Provider mutations share these POST suffixes under /api/v1/module-vms/, /api/v1/module-containers/ and /api/v1/module-admin/:

Suffix Fields beyond workspace_id and instance_id
preview preview_id returned by a module action; reads the host confirmation
commit preview_id, confirm:true and an Idempotency-Key header
history None; returns this panel's permitted operation history
operation operation_id; inspects current outcome without replay
resolve operation_id, confirm:true and selected vm_ids or resource_ids
forget operation_id and confirm:true; removes terminal receipts after node acknowledgment

The host classifies effects and freezes resource identities before confirmation. A retry uses the same key and returns the same intent. Unknown outcomes require inspection. Resolve records that inspection; it does not establish success or dispatch another action.

VM adapter receipts include the immutable profile and declared consistency. An adapter_orphan_ack_required response permits a separate retry with acknowledge_orphans:true. This removes only terminal local receipts when the original system identity is absent or changed. Active provider tasks remain retained. A transient connection failure requires cleanup retry, not local-only removal.

Power acceptance means queued. A lost SSH connection does not prove shutdown. See libvirt, Proxmox, containers and administration for provider-specific limits.

A permitted console module action returns an opaque viewer_ref. POST /api/v1/viewers/{reference}/tickets issues one single-use ticket valid for 15 seconds. Open the same-origin WebSocket /api/v1/viewers/{reference}/stream and send {"type":"auth","ticket":"..."} first. The URL must have no query string. Provider addresses and temporary passwords never enter browser messages.

Binary output contains bounded Guacamole display instructions, not raw provider bytes. Text input uses {"type":"input","instruction":"..."} or processed-byte acknowledgments {"type":"ack","bytes":N}. Only permitted input instructions pass; clipboard and file channels are refused. Current authority remains checked during the stream. See remote displays for input release and time limits.

Runtime policy administration#

Policy administration requires an unrestricted local owner credential with policies:manage. It remains available for recovery when normal policy decisions fail. It cannot be delegated through project membership.

Route Method Result
/api/v1/policy-status GET Current revision and enforcement availability for the caller
/api/v1/policies GET Owner inspection of state, publishers and installed manifests
/api/v1/policy-publishers PUT Explicit trust update with ID, public key, enabled state and revision
/api/v1/policy-packages POST Verify and install archive_base64; no activation
/api/v1/policy-packages/{digest} GET Download the verified signed archive
/api/v1/policy-activation POST Prepare and activate a digest with the expected global revision
/api/v1/projects/{id}/policy-roles GET Current project role bindings
/api/v1/projects/{id}/policy-roles/{subject} PUT Replace roles with an expected binding revision
/api/v1/policy-preview POST Compare host, policy and effective permission for 1 to 64 requests

Preview requests contain an action and optional node_id, root_id and labels. An optional digest selects an installed candidate. Only the local owner can select a candidate or supply subject_id/project_id for another identity's membership ceiling. A normal preview uses the authenticated credential. The runtime decision contract is documented in the policy SDK. See policy operations for revocation, rollback and restore.

Inference and models#

See the inference API contract for model acquisition, service lifecycle and compatible streaming endpoints.

Cluster federation#

See the federation API for project-scoped pairing, grants, compatible inference, remote management and resumable model acquisition.

FICC / DocumentationBack to top

Search documentation

Press Escape to close

Loading search...

    Reading appearance

    Choose colours, surfaces and text independently. These settings are saved for this documentation site in this browser.

    Flat surfaces remove decorative materials. Typography is a separate choice. Increased contrast uses the Contrast palette. System forced colours always take precedence.