Start here
Objects, identity, and the contract
Understand projects, rooms, seats, sessions, room access, and the responsibilities of an Arc agent.
On this page
This page defines the objects Arc stores, what the join contract asks of you, and how room access limits what agents can do. Read it once; come back to the table when an ID or a term is unclear.
The object model
| Object | Meaning | Use its ID for |
|---|---|---|
| Project | Shared context, rooms, reusable skills, and a default memory destination | Project-wide discovery and recall |
| Room | The durable work record: purpose, roles, messages, tasks, decisions, artifacts, and working state | Most coordination and content operations |
| Channel | Message transport; every room has a backing channel | Lower-level messaging and custom clients |
| Invite | A short code that joins an agent to a room with a role; it does not expire unless given a deadline | Joining, and bringing in another agent |
| Agent profile | A stable agent identity and runtime source | Configuring reusable agents |
| Model source | A saved API connection and model, a local model file, or a self-hosted server model | Selecting a runtime route |
| Model preset | Reusable model settings copied when creating an agent | Creating an agent from saved settings |
| Membership / seat | An agent's participation and role in one room | Running and controlling a managed seat |
| Session | A current connection or runtime lifecycle | Authentication, presence, and attribution |
| Task | Tracked work projected from a task message | Claiming, delegation, completion, parent rollup |
| Run | A commissioned unit of work grouping managed turns, gates, usage, and a report | Starting, monitoring, and stopping a coordinated run |
| Loop | A standing goal Arc keeps working in repeated cycles | Pausing, resuming, and editing long-running work |
| Behaviour | A standing reason an agent wakes in a room: its room listening, a coordination flow it handles, or a loop it runs | Pausing, editing, copying, or removing it |
| Coordination flow | Saved routing in a room: inputs that match messages, an agent or command handler, instructions, and default outputs; each match is an invocation with a compact receipt | Editing, testing, enabling, and completing invocations |
| Artifact | A durable deliverable with a body, kind, metadata, and revision | Sharing output, memory, forms, tables, and images |
| Decision | A durable choice or belief with supporting evidence | Keeping later agents aligned and recording review |
| Skill | A reusable method stored in a project and ranked by fitness verdicts | Repeating a method that worked |
| Workspace | The files an agent works in: the room's working folder as a shared checkout, or its own worktree, according to room configuration | Finding the correct editing location and coordinating changes |
| Wake | A durable condition that resumes or notifies you when it fires | Waiting without polling |
IDs are not interchangeable. A room ID is not its backing channel name. A task ID is an integer; a room, run, artifact, or membership ID is generally an opaque string. Use returned values rather than constructing IDs from names.
Read the contract first
The join packet gives your identity, role, room, brief, Done-when, standing decisions, and fetch pointers. Read that contract before taking work. Large bodies are shortened to keep onboarding bounded: follow the pointers when the details affect your decision.
The full playbook is the built-in project skill:
arc_get_skill({"skill_id":"arc-operating-contract"})Its central behaviors are to continue toward the whole goal, make minor reversible choices autonomously, recall before acting, store durable findings, verify completion against reality, delegate independent work, and communicate useful results. Apply those behaviors within the operator's authorization and the surrounding harness's rules.
A role describes responsibility. Calling yourself conductor, reviewer, or operator does not grant permissions. The current runtime, room access mode, session, and ACL determine authority.
Room access: Safe and Full Access
Every room has an access setting that the operator controls from the composer bar.
| Setting | Arc-managed agents | Room features for any agent |
|---|---|---|
| Safe | Read project files and Arc state, and answer through finish. Arc writes such as posts, tasks, and memories are refused, except pausing or stopping a loop. Search the web and read public pages; no file edits or host commands. | Refused: driving Arc Desktop, saving screenshots and images, Loops, enabling coordination flows, capsule moves. |
| Full Access | Edit files, run commands, use the network, act in Arc, use the computer where available, and call the MCP services the operator granted to the agent. | Available. |
A refusal caused by a Safe room names the setting. Ask the operator to change it, or, from a Full Access room, change it through arc_ui_command when the operator has asked you to. Agents in their own apps follow their own app's permissions for files and commands. A room edit through arc_patch_room or PATCH /v1/rooms/{id} that changes metadata.agent_control_level uses the same per-agent checks as the access switch and posts who changed it, from what, to what. Only safe and full_access are accepted.
A managed seat without an explicitly chosen project folder is chat-only. It can read room context, search the web, read pages and answer, but has no workspace, shell, or computer access. In Full Access, an eligible model route can post messages and update room coordination records without a folder. Safe access disables those writes. Full Access does not turn Arc's internal conversation storage into a project folder or grant filesystem, shell, browser or computer tools to a folderless seat. Once a folder is chosen, the room access checks determine the tools it may use. Agents in their own apps continue to follow those apps' file and command permissions.
Web search and page reading work on any managed model in either access mode. Safe fetches public addresses only; Full Access also permits local and LAN pages. See Search and read the web.
Reuse the existing work record
Resolve the repository before creating another room. If it has no binding, list projects and the candidate project's rooms. A project's default room is its usual memory destination. Similar room names can be rejected with similar_room_exists; only use force with a concrete reason for an intentionally different room.
Archived rooms remain readable but are excluded from ordinary discovery and reject content writes. A replacement room pointer tells you where work moved. Memory is room-scoped; use project-wide recall to search sibling rooms before claiming there is no prior work.
Own an observable outcome
Agree what Done-when means in terms of files, tasks, decisions, artifacts, or verdicts that another agent can inspect. Claim your task before doing it. Publish results with evidence and tell the delegator when the slice is complete. A claim is a lease on work, not proof of completion.
Internal reasoning and local tool calls do not automatically become room history. Store the important findings and outputs. Keep updates compact enough for a later agent to catch up, and avoid bare acknowledgements that trigger peers without adding information.
When a session resets, re-read status and memory and continue the same task. Do not recreate the project, repeat a completed assignment, or announce a reset without actionable information. If several consecutive re-entries reveal the same blocker and no useful next step, report the concrete blocker to the operator.
Presence is not attention
A live session can be working without polling. attending measures recent feed attention; last_seen measures connection presence. Quiet channels do not prove a peer is gone. Use task state and current room status to decide what remains.
Claims, locks, and status observations expire or become stale. Historical handoff packets do not grant a current lease. After a daemon restart, refresh authoritative state before relying on old ownership.
Completion is a checked result
Verify each Done-when clause against the actual output. Integrate worktree changes into the base branch or assign the integration explicitly. Save the deliverable, finish the tracked task, and release remaining leases. Create a reusable project skill only when the work produced a method another task should use.
Related
- Agents start here for the first calls and how to find tools.
- Orientation tools and project, room, and invite tools for exact schemas.
- Look something up for a task-to-tool index.