## Thinking Path > - Paperclip manages AI agents and the environments where they run. > - Cloud owners can receive instance-admin rights for their own dedicated instance through the existing owner setting. > - Authentication computes these rights for each request without storing an instance-admin role. > - The board UI reads `/api/cli-auth/me` to decide whether to show administration controls such as Tailscale. > - That response used only stored roles, hiding controls that the Cloud backend already authorized. > - This change reports the effective Cloud request rights so the UI agrees with the backend. ## Linked Issues or Issue Description **What happened?** A Cloud owner with `enableOwnerInstanceAdmin` enabled can successfully read Tailscale connections, while `/api/cli-auth/me` reports `isInstanceAdmin: false`. The Connectors page therefore hides Tailscale. The same stale summary can hide other instance administration controls. **Expected behavior** The access summary should reflect the Cloud request's effective privileges. Turning off owner elevation must remove those privileges on the next request. Session and board-key callers must continue to use the fresh stored-role snapshot. **Steps to reproduce** Sign in as a Cloud stack owner with owner instance-admin elevation enabled and no stored instance-admin role. Open Connectors and compare the access summary with a Tailscale connections request: the summary reports no admin access even though the backend permits the request. Searched existing PRs for `"cli-auth/me" cloud` and `tailscale access`; no duplicate fix was found. Related: [#21526](https://github.com/paperclipai/paperclip/pull/21526), which added device sign-in and exposed this hosted permission-summary gap. ## What Changed - `/api/cli-auth/me` uses the trusted Cloud actor's computed `isInstanceAdmin` value for `cloud_tenant` requests. - Session and board-key requests retain fresh stored-role checks. No roles are persisted and no authorization gates or owner settings change. - Regression tests cover Cloud elevation and de-elevation, non-Cloud stored access, and rejection of anonymous/agent callers. Tailscale documentation explains Cloud owner access. ## Verification - Reproduced the deployed mismatch in an authenticated Cloud owner browser session: the access summary reported false while the Tailscale list request succeeded. No feature connection or configuration was changed. - Both Cloud access regression cases failed before the fix. - `pnpm exec vitest run server/src/__tests__/cli-auth-routes.test.ts server/src/middleware/cloud-tenant-actor.test.ts ui/src/pages/apps/TailscaleConnector.test.tsx` passes: 88 tests. - `pnpm --filter @paperclipai/server typecheck` passes. - `pnpm verify --explain` exits 2 and selects broad CI. All 57 checks pass on final head `6044d5097396de95f49bcbb7ce7bbb1e445a80fa`; no checks remain pending. Greptile scored this head 5/5 with no unresolved comments, and the branch is conflict-free. - `git diff --check` and a local credential/PII scan pass. - The fix has not been deployed or accepted in a hosted browser yet. ## Risks The summary exposes administration controls to Cloud owners already authorized by the backend. Non-owner access and disabled elevation remain denied by the existing authentication policy. No migration, provider configuration, or deployment change. ## Model Used OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through Codex in T3 Code, with xhigh reasoning. Context window size was not exposed. No subagents. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have described the issue in-PR following the bug template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket or instance details - [x] I have run tests locally and they pass - [x] I have added regression tests - [x] I have updated relevant documentation - [x] I have considered and documented risks - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no unresolved comments - [x] I will address actionable reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>
13 KiB
Use Tailscale machines in SSH environments
The Tailscale connector gives Paperclip access to a tailnet. Paperclip joins a separate device to that network, then uses the existing SSH environment driver to run tasks on selected computers. The connector is managed from Connectors and can serve multiple SSH environments in the same company. The computer is not replaced or provisioned by Paperclip.
In Connectors, find Tailscale, open it and click Connect Tailscale Network. After approving consent, click Create SSH environment, or create an SSH environment and select Tailscale under Network. Choose the connection and machine, then configure the SSH user, port, absolute workspace path, private key, and trusted host keys. The Tailscale network option appears once a tailnet is connected. On a Mac with the normal Tailscale application, enable macOS Remote Login. Tailscale SSH server support on macOS requires the open-source tailscaled variant; ordinary OpenSSH over Tailscale works with the standard Mac application.
Device sign-in opens Tailscale in a separate tab and keeps the connector page open. A normal sign-in link remains available if the browser blocks the tab. Approve the Paperclip device in your own tailnet; no OAuth app, API key, Cloud broker credential, or per-instance pilot admission is needed. If your tailnet requires device approval, the connector shows that separate pending state. Sign-in expires after ten minutes and can be cancelled from the connector.
SSH setup hides the Network selector when Direct connection is the only available option. A sole connected tailnet is selected automatically and its connection selector is hidden; multiple connected tailnets remain selectable. Switching an existing environment to Direct connection clears its saved Tailscale machine and credential references and saves the direct host you enter.
After selecting a machine, Prepare machine pairing creates an SSH key in
Paperclip’s vault and displays a command containing only the public key. Each
preparation generates a fresh key pair. The command uses the public key produced
during that request, never mutable metadata from a saved secret. Run it
as the target SSH user. The command preserves existing authorized keys, including
files without a final newline. Before installing the key, it checks for readable
Ed25519, ECDSA, or RSA host public keys in /etc/ssh and stops without changing
authorized_keys if none are available. It prints that user's name, home
workspace path, and known-hosts entries for every available host key for the
form. You can also select an existing SSH private key secret.
Pairing output is tied to the selected company, tailnet, machine, and SSH port. After editing the port, prepare pairing again for matching known-hosts output. A late response for an earlier port cannot replace the selected private key. Switching to Direct connection or closing the form also prevents pending pairing results from changing the selected key.
Save the environment and test it. Select it as an agent’s environment and choose any harness supported by SSH environments. Select the agent's AI account in Paperclip. Runs use that account's subscription or API key, with private credential directories on the target computer, just as sandbox runs do. The computer supplies the installed harness and workspace; its SSH user's provider login is not used for an agent with a configured AI account. Test the chosen harness separately: SSH access does not prove provider authentication.
SSH's Advanced section includes Use authentication configured on the remote machine. New environments leave it off, requiring the agent's Paperclip AI account. Turn it on to use the remote user's provider login instead. Existing SSH environments display it as on; opening or upgrading an installation does not rewrite their saved configuration. The same option applies to direct SSH and Tailscale connections.
The environment keeps the ssh driver. Machine selection stores the connector
ID and Tailscale’s stable device ID, and runtime
resolution looks up its current address through that connection’s private
socket. Offline, removed, disconnected, and wrong-company machines fail closed.
The host’s existing Tailscale connection is never a fallback.
Device sign-in and credential custody
It is a network connector on the Connectors surface; it does not publish agent
tools or enter MCP discovery. Management requires an instance administrator with
access to the company. Only the person who started a pending sign-in can retrieve
its sign-in link. Existing SSH environment access governs which agents execute
there. Cloud and self-hosted instances use the same Tailscale device sign-in.
For Cloud owners, the board access summary reports the effective instance-admin
rights computed by Cloud authentication while enableOwnerInstanceAdmin is
enabled. Disabling that setting removes those rights on the next request.
The instance starts a private userspace Tailscale device and returns its generated
https://login.tailscale.com/a/... sign-in address. Pending device state is stored
in the configured company vault before the address is returned. The active
tailscale up command watches Tailscale state until consent and any required
device approval complete, or the ten-minute deadline expires. It saves the
registered device state before marking the connection connected. Pending sign-ins
can resume from the saved state after a server restart without extending their
deadline. There is no background database scan: browser progress requests exist
only during the bounded sign-in, and the CLI waits for Tailscale state events.
The previous OAuth callback remains available for already-started pilot flows; existing enrolled devices continue to use their saved state. New connections use device sign-in and do not call the Cloud OAuth broker.
The connection records the exact trusted vault version and a SHA-256 digest of the server-written value. Runtime reads that version and verifies its digest. A generic company secret rotation cannot change the authorized network. Trusted node-state saves advance both fields together, with a compare-and-set guard so an older save cannot replace a newer state. Reads keep using the previous trusted version until the new version is committed. Private node state, digests and enrollment credentials never appear in connection or environment responses.
Enrollment tokens and node state are server-owned secrets with a durable
system_purpose classification. Generic company catalogs omit them. Generic
bindings, environment injection, and agent value reads reject them, including
bindings saved before the restriction. Renaming or rotating a secret cannot
remove this classification. Disconnecting or replacing a connection leaves its
old credential protected. Only the connector's server consumer can resolve its
trusted value; an SSH environment binds its private key, never the node state.
Unclassified legacy node-state values are also rejected by generic reads,
including state left behind by an earlier connection replacement.
Migration 0482_aberrant_rumiko_fujikawa classifies existing connector-referenced secrets.
Apply it before running the updated server. If node state was copied before
this restriction, revoke that enrolled device in Tailscale; a local disconnect
cannot stop a copy outside Paperclip.
Connections created before migration 0481_round_pet_avengers have no trusted version
and digest. They fail closed and require a fresh Connect Tailscale Network
consent. The migration leaves these fields empty; it does not trust or backfill a
generic secret's latest value.
Each connection has a separate userspace daemon and private socket. A stale credential read reloads the trusted value before replacing a ready daemon and rechecks which daemon is active after the reload. It preserves a healthy newer socket and cannot cross a manager shutdown. Failed connection requests leave cleanup to the network manager's exact client; they cannot disconnect a newer retry using the same connector identity. The daemon accepts no subnet routes or DNS changes and blocks incoming connections. Normal shutdown saves node state and removes temporary files. A restart restores the enrolled device; it does not reuse the OAuth token or require consent for every task. Disconnect invalidates pending consent and stops the connection’s local daemon. A callback already exchanging or saving credentials cannot reconnect after disconnect or replace a newer authorization. Completion retains the consumed state's digest as a private attempt marker, with no expiry; disconnect replaces that marker.
Database writes and credential reloads verify ownership without holding a database lock across broker or daemon startup. Cancelled attempts close their daemon and remove their newly created secret without touching a newer connection's state. Disconnect does not remove the target computer from Tailscale.
Company deletion removes connector records before vault secrets in the company transaction. After commit, it stops every daemon owned by those records. A rolled-back deletion leaves the connector and its daemon intact. Deleting a connector's vault secret invalidates pending consent, disconnects its network, and clears the trusted credential reference before removing the secret. If shutdown fails, the disconnected reference remains available for a deletion retry. Late daemon state writes cannot restore a retired connector.
Task runtime resolution obtains its socket from this same guarded connection service after loading the SSH key. It requires the connection to remain connected with the environment's saved credential identity during credential reload, daemon startup, and device discovery. A disconnect or replacement rejects the run before returning a socket; runtime resolution cannot restart the connection from a stale saved secret. Saved network credentials without a connector and machine selection are rejected; all Tailscale environments use the connector's lifecycle.
This implementation currently supports one serving process per instance. Concurrent replicas need a durable connection ownership lease before rollout.
Tailscale identity belongs to the persisted machine key in the saved node state,
not the container ID or hostname. A redeploy must retain both the database's
encrypted node state and the same vault master key. Cloud already materializes
the stable per-stack PAPERCLIP_SECRETS_MASTER_KEY across release rolls. Do not
make the connector ephemeral or replace its node state at each start. Losing
that state, device removal, or a tailnet reauthentication policy can require
fresh consent. The app-owned device has the consenting user's tailnet rights.
Local development
Run the Paperclip instance at http://localhost:3100. No local Cloud broker or
Tailscale OAuth app is required. The instance needs tailscale and tailscaled.
For a separate local userspace client, install the pinned programs outside the
checkout:
GOBIN="$HOME/.local/share/paperclip-tailscale/bin" go install tailscale.com/cmd/tailscale@v1.104.5
GOBIN="$HOME/.local/share/paperclip-tailscale/bin" go install tailscale.com/cmd/tailscaled@v1.104.5
Set PAPERCLIP_TAILSCALE_CLI and PAPERCLIP_TAILSCALED to their absolute paths.
These settings can be set in the supported .env files. Each new client reads
them at startup, after environment loading.
Verification and rollout gates
Offline tests cover device sign-in without an auth key, saved state and restart, separate company identities, initiator binding, cancellation and expiry, stale completion, trusted credential versions, device approval, popup fallback, and route authorization/CSRF. Existing tests retain legacy broker callback, SSH, pairing, and network lifecycle coverage. These do not prove live consent or remote execution.
Before rollout, qualify two unrelated customer tailnets through ordinary device sign-in, machine discovery, and an agent task using its selected AI account that writes a file on the selected computer, result streaming, cancellation, server restart, machine sleep/reboot, and revocation. A local instance whose public URL is localhost also needs an API path reachable by the remote agent for tasks that call back to Paperclip unless the adapter uses the existing remote callback bridge. Production Cloud uses its public HTTPS stack URL.
The connector's bundled artwork comes from the vendor's
https://tailscale.com/favicon.png, copied without modification (SHA-256
680570c9090b604450792f68ceed10beeb33a69c9bccc2a92e398564c7075a5c).
The old managed OAuth profile remains disabled unless explicitly configured for its existing pilot. Its same-tailnet registration restriction does not apply to the new device sign-in path. Do not configure a customer-specific OAuth app or admit a pilot instance to make device sign-in work.
Provider references: