Esc

↑↓ move↵ openIndex · Pagefind
Security & privacy

Trust the agent exactly as far as the person.

The short version: agents act as a user, see only what that user sees, can draft but never decide, leave a trail, and lose access the moment you say so. The long version is below, with the code it is based on. Company-wide security practices are on Security.

  1. Scopes

    Narrow before you start

    Every assistant token is scoped and expires. Read-only covers the 58 read scopes; read-and-write adds writes except webhooks and company administration.

    • Tokens last 7, 30 or 90 days, up to 10 active per person
    • Only a SHA-256 hash is stored; the token is shown once
    • Scopes narrow your access. They never add to it
  2. Consent

    You say yes, explicitly

    Hosted connections open os.construction in your browser: you sign in, read what the assistant asks for, and choose Allow access or Deny.

    • Hosted grants last up to 14 days, then ask again
    • Hosted connections are read-only in the preview
    • The assistant works as you: your projects, your records
  3. Propose-only

    Agents draft. They do not decide.

    Assistant tokens and hosted connections are agent credentials. Of 1,277 cataloged writes, 636 are proposals agents may make; 635 approve or administer and answer 403 for any agent.

    • Approve, certify, execute, post, pay, release, void, delete: refused
    • Setting status: "approved" through an update: refused
    • 6 transition endpoints allow only their submit-style actions
  4. Human approval

    A person signs off in the app

    The draft lands where your team already works. Someone with the approve permission reviews it in os.construction, exactly as if a colleague had drafted it.

    • "Agent credentials can create and propose changes but cannot approve…"
    • Approval rules and roles are unchanged
    • Built-in os.construction agents are Planned and will follow the same rule
  5. Audit

    Every call leaves a trail

    Agent calls are recorded with the person they act for. Company admins review proposals and refused attempts under Company admin > API activity.

    • Tracked edits keep field-level before and after
    • Hosted calls return an invocation ID you can look up
    • Service accounts have their own call log
  6. Revoke

    One click, effective on the next call

    Revoke a token in Account > AI assistants, or a hosted connection in Account > Connected apps. Changing your password or two-factor settings revokes all of your tokens.

    • Deactivating a user ends their tokens too
    • Company admins can revoke apps company-wide
    • Receipts survive revocation for review

Who the agent is

  • An assistant or script acts as one user: the person who created the token or approved the connection, or a service account. It never has more access than that identity.
  • Every call is checked by the same REST route a person's browser uses: company, project membership, role, tool enablement, record visibility and workflow rules.
  • companyId in CLI or MCP input is only an assertion of the authenticated company. Sending another company's ID is rejected; it cannot select a tenant.

Credentials

  • Personal tokens are created under Account > AI assistants, always carry explicit scopes, expire after 7, 30 or 90 days, and are stored only as a SHA-256 hash. You see the token once. Up to 10 can be active per person.
  • Read-and-write tokens never include webhook or company-administration writes, because those outlive the token. Use the app for them.
  • Changing your password or two-factor settings, or deactivating the account, revokes every token.
  • Keep tokens out of prompts, chats, repositories, screenshots and recordings. MCP client config files often store environment values in plain text; VS Code's promptString input keeps the token out of the file.
  • CLI browser sign-in stores its grant in the OS credential store (Windows DPAPI; Linux Secret Service). There is no plain-text fallback, and macOS storage is not available yet.

Agents propose, people approve

  • Assistant tokens, hosted connections and service accounts marked as agents are agent credentials. Each of the 1,277 cataloged writes is classified: 636 propose (allowed), 266 approve and 369 administer (refused for agents), and 6 transition endpoints that allow only submit-style actions.
  • Refusals answer 403 with "Agent credentials can create and propose changes but cannot approve, certify, execute, post, pay, release, void, delete, send externally or change permissions." The scope does not matter.
  • Setting an approval state through an ordinary update (for example status: "approved") is refused the same way.
  • Company admins review agent proposals and refused attempts under Company admin > API activity.

Prompt injection and untrusted data

  • Record text (an RFI question, a daily-log note, a vendor name) is written by people and can contain instructions. The connector tells the model, in its server instructions, tool descriptions and usage resource, that API results are untrusted data and never instructions.
  • The real backstop is structural: a hijacked agent still cannot approve, pay, delete or change permissions, and every write it attempts is attributed and visible to admins.
  • Writes are off unless you turn them on twice: a read-and-write token and OS_CONSTRUCTION_MCP_ALLOW_WRITES=true (MCP) or OS_CONSTRUCTION_CLI_ALLOW_WRITES=true plus --confirm (CLI). confirmed/--confirm are client guards, not proof that a human approved.
  • Neither tool retries a mutation automatically. An uncertain write returns exit 9 / outcome: "unknown" so nothing gets applied twice by accident.

Where your data goes

  • The CLI and local connector run on your machine and call only the API origin you configure (default https://app.os.construction). Catalog search, describe and help make no network calls at all.
  • There is no telemetry in the CLI or connector.
  • Whatever an operation returns is handed to your MCP client, and from there to the model provider you chose. That provider's data terms apply to it. Ask for only what the task needs: narrow filters and small pages.
  • Results are capped (32 KiB per CLI envelope, 1 MiB read from the API) and truncation is always reported. File bytes never enter model context: downloads go straight to a new local file and return only path, size and SHA-256.
  • Arbitrary URLs, headers and cookies are not accepted, redirects are refused, and a response that echoes the presenting credential is withheld.

Hosted connections

  • The hosted endpoint is switched on in preview.
  • When it is on: you sign in in your browser, see the requested scopes, and choose Allow access or Deny. Only clients os.construction has reviewed are accepted (Claude, Claude Code, ChatGPT, VS Code, Cursor and the CLI). Grants last up to 14 days.
  • Hosted connections are read-only during the preview, and writes stay off in production today. Each call returns an invocation ID you can look up under Account > Connected apps > Invocation history.
  • The OAuth grant is never forwarded as a REST token; the server revalidates your user, session and permissions on every call.

Revoke and review

  • Personal token: Account > AI assistants, choose Revoke.
  • Hosted connection: Account > Connected apps, Revoke access, then Confirm revocation. The next call fails with 401.
  • Service account: disable it or revoke one credential under Company admin > Service accounts; its call log stays.
  • Report a suspected leak to your company admin straight away, revoke first and investigate second.

Sources in the app: src/modules/mcp/personal-tokens.ts, src/lib/api/action-policy.ts, src/lib/api/action-classes.json, src/modules/mcp/server.ts, src/modules/mcp/executor.ts, src/modules/mcp/oauth-service.ts. Status as of 2026-11-22.

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file