> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/agents-identity-and-data/bring-your-own-agent.md). # Bring Your Own Agent operations Use this runbook for the loopback NIGHTSHIFT MCP gateway, connection-owned paper sessions, and the separate DPoP-bound Hyperliquid testnet handoff. The reviewed MCP deployment is local-only. It has no signing, venue submission, cancellation, retry, funding, transfer, withdrawal, or mainnet authority. ## Before issuing a connection 1. Start NIGHTSHIFT through the normal supervisor and unlock an authenticated operator session. 2. Confirm `/api/health` is `200` and reports `agentAccessState=ready`, `agentPaperState=ready`, `agentMcpActiveConnections` at the expected value, and `allowMainnet=false`. 3. Confirm the signed Agent Pro entitlement is active. Entitlement permits connection issuance; it never enables a signer. 4. In **Agent Command Center**, choose the exact capability mode, symbols, optional public account grant, lifetime, hourly budget, and paper envelope. Paper USD values are canonical exact decimals and the lifetime is capped at 24 hours. 5. Review the scope before selecting **Create connection**. Copy the one-time MCP configuration immediately. NIGHTSHIFT retains only a server-keyed digest. The generic client configuration is an MCP Streamable HTTP server at `http://127.0.0.1:3000/api/mcp` with `Authorization: Bearer `. The client must negotiate MCP `2025-11-25` and send both `application/json` and `text/event-stream` in `Accept`. Do not place the secret in a URL, prompt, repository, browser storage, analytics, or model-provider configuration that is synchronized to a third party. ## Capability verification * Research lists only selected market, account, risk, and activity reads. * Propose adds strict advisory proposal creation and status. An accepted proposal still requires the independent operator review and fresh AEGIS path. * Paper adds `nightshift.paper.v1.start_session`, `nightshift.paper.v1.place_order`, and `nightshift.paper.v1.get_session`. It does not add proposal or venue-execution authority. * `tools/list` must never contain a sign, submit, cancel, retry, fund, transfer, withdraw, policy-edit, or arbitrary HTTP tool. * Account reads work only for the exact lowercase public address granted at connection creation. A paper client generates one UUID session ID, starts the session idempotently, and submits unique `paper_...` intent IDs. Every order is simulated once against a fresh normalized public book. Increasing exposure additionally requires fresh exact marks for every open paper position. The immutable connection policy enforces venue, symbols, capital, daily loss, drawdown, entry spread, entry slippage, per-market notional, portfolio notional, frequency, and expiry. Reduce-only orders can only shrink the matching simulated position. The Command Center shows connection-owned paper session state, fill/position counts, risk locks, recent fixed-code activity, expiry, and revocation. Session or activity data never grants capital authority. ## Hyperliquid testnet handoff Testnet execution is deliberately not tunneled through an MCP bearer tool. Create a separate policy in **Agent Pro Automation** for the same agent ID and provide only the client's P-256 public JWK. The client keeps the private P-256 key and calls the versioned `/api/agent/v2/automation` API with the same short-lived agent secret using the `DPoP` authorization scheme and a fresh bound proof. That direct API remains Hyperliquid-testnet-only, repeats live credential, entitlement, policy, portfolio, AEGIS, fee, and signer checks, permits at most one signer attempt per automation request ID, and exposes ambiguous results only through same-ID reconciliation. MCP cannot create or weaken the policy, forward the proof, reach the signer, cancel, or retry. Follow [agent-automation.md](/nytshift-docs/agents-identity-and-data/agent-automation.md) for the full policy and incident procedure. ## Revocation and compromise For one lost or suspect client secret, select **Revoke** on that connection. Authorization is rechecked on every MCP call, so existing transport sessions lose access immediately. If a testnet policy is attached, revoke that policy separately because revoking an MCP transport session is not an order cancellation. For a broader incident: 1. Use **Revoke all** for agent credentials and **Stop all automation** for DPoP policies. 2. Keep execution kill switches active. Never infer that revocation canceled an already attempted order. 3. Preserve `agent-access-v1.json`, `agent-paper-v1.json`, and `agent-automation-v1.json` plus the relevant backup and fixed request IDs. 4. Reconcile every ambiguous testnet request by its retained ID. Do not resubmit. 5. Rotate the operator secret and commercial signing configuration if their exposure is suspected, restart, and issue new short-lived connections only after health is clean. ## Store failure and recovery The default checkpoints are under `~/.nightshift/data` (or `%USERPROFILE%\.nightshift\data` on Windows). `agent-access-v1.json` contains digests, mandates, MCP policy, and fixed activity receipts; `agent-paper-v1.json` contains connection IDs, immutable policies, exact simulation ledgers, and risk state. Neither contains plaintext agent secrets, model credentials, venue credentials, wallet keys, prompts, or conversations. Do not hand-edit or delete a failed checkpoint. A malformed access or paper configuration/store makes `/api/health` unsafe and connection management fails closed. Preserve the bytes, stop the supervisor, and use only verified backup commands: ```powershell pnpm backup:create pnpm backup:list pnpm backup:verify -- pnpm local:stop pnpm backup:restore -- pnpm local:start pnpm local:health ``` After restore, keep execution stopped, inspect every restored connection and paper risk lock, revoke all restored automation policies, and deliberately reissue credentials. A restored digest can restore an older revocation view; restore is never authority to resume unattended activity. ## Remote activation gate The current MCP transport rejects non-loopback requests even over HTTPS. Do not expose it with a tunnel, port forward, public reverse proxy, or Cloudflare rule. Hosted access remains unavailable until customer-bound OAuth 2.1 authorization code with PKCE, exact redirect registration, audience-bound short tokens, rotating refresh tokens, TLS, managed secrets, centralized abuse controls, privacy review, interoperability evidence, and an independent exact-release security rehearsal all pass. Configuration alone must not change this gate. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://nytshift.gitbook.io/nytshift-docs/agents-identity-and-data/bring-your-own-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.