Skip to content
Maglev docs

Connect your agent

Pick your agent, copy the block, paste it into the agent’s chat from your hardware project folder. Your agent installs what is missing, reads the docs, checks the account connection, configures the project and reports back. You approve the matching login code in your own browser when needed.

The first result is a verified account and configured project. Supplier contact, file uploads and paid actions need their own authorization. Keys remain in your private local profile or host environment; never paste them into chat.

Open Claude Code in your project folder and paste this. Plain text copy: claude-code.txt.

Connect Maglev to this existing project. Run the setup with your own command tool and continue until you can report the actual connection result.


1. Read https://trymaglev.com/assets/connect/claude.md and https://trymaglev.com/docs/release.json. Use the exact versioned installer in that official guide and this project's directory. Do not scan the home directory or choose engineering files as part of connecting.
2. Check Node.js 22.13 or later with `node --version`. Use an already-authorized installation method if it is missing; otherwise explain the prerequisite or host approval needed. Do not bypass host restrictions or edit permission rules.
3. Run the installer yourself in a process session that stays open while I approve the matching login code in my browser. Reuse saved login when available. If the browser cannot open, show its printed approval URL and matching code. Do not approve for me, ask me to repeat the installer in my own terminal, or ask for my password or key. Do not ask me to paste the key into this chat.
4. Follow the installer's recovery instructions. Preserve custom project settings and instructions; do not delete them to suppress a conflict. An invalid MAGLEV_API_KEY override needs my choice before switching accounts, and its value must never be printed. Keep private backups and credential files out of chat.
5. Read https://trymaglev.com/SKILL.md. Use the guide's pinned CLI prefix through your existing command tool to check the account and continue in this conversation. If MCP tools are available, verify get_identity. A new configuration may require the host to reload; do not claim its tools are loaded until an actual call succeeds.
6. Report the installed versions, project configuration and skill paths, verified connection mode and any remaining host step. Do not run a demo, read engineering files, upload, contact suppliers, approve deliveries or start paid work as part of setup. Then ask what I want to make.
Step What happens What it needs from you
Prerequisites Checks Node.js 22.13 or later and installs it if missing Nothing, unless the machine needs your password to install
Install Supported agents run the versioned native installer in this project Nothing, unless the host requests execution approval
Learn Reads the agent index, the skill and the guides, and keeps their rules Nothing
Account Installer verifies saved login or opens browser sign-in Approve the matching code in your browser; HTTP-only hosts use their secret settings
Project Configures the project while preserving unrelated settings A host reload may be needed for MCP; the pinned CLI works in the current conversation
First result Confirms connection mode and scopes Nothing
Report Tells you what it can now do and which decisions are yours Your priorities for the real project

The block is a prompt. If your agent skips a step, tell it which one.

Run it yourself

Section titled “Run it yourself”

Requires Node.js 22.13 or later and npm.

Terminal window
npm install -g https://trymaglev.com/downloads/maglev-cli-0.6.14.tgz
maglev setup

This installs CLI 0.6.14; setup pins MCP 0.2.14 from the matching hosted archive. The npm registry still serves earlier versions. See install, checksums and upgrades.

Run maglev setup from the project folder. Sign in as your organization’s owner, match the code shown in your terminal, and choose Connect terminal. The CLI saves the key privately on this computer. You do not copy a key. Then use ↑ / ↓ to select Claude Code, Codex, another MCP agent or terminal only. Reopen your agent and accept its project connection prompt.

The default connection is live. For a synthetic walkthrough, run maglev login --sandbox first, or maglev setup --demo. For automation, supply MAGLEV_API_KEY or an existing saved login and run maglev setup --target codex --json. Connection and recovery details.

A live key enables project, directory, knowledge, action and approved-delivery tools. Engineering file transfer additionally needs an owner grant. The delivery guide explains exact review, real effects and recovery.

Give your agent a first job

Section titled “Give your agent a first job”

Use Maglev to review this project for manufacturing. Ask me about missing requirements.

Your agent can ask which files to use during the task. Setup does not need a second file-location interview. In Claude Code, invoke /maglev-manufacturing; in Codex, $maglev-manufacturing.

Name the outcome, quantity, timing, geography and tradeoffs:

Use this project’s released enclosure drawing and BOM to prepare a quote request. Build in the US. Keep the specified alloy; quality matters more than the lowest price. Ask me about missing requirements before contacting anyone.

Discovery can filter country and material and optimize cost or speed. It has no quality score, so your agent must preserve a quality requirement in the brief rather than translating it into “cheapest”. Maglev’s API does not see a folder because you provide its local path: it receives the text and structured fields your agent sends. Interview messages and requests are stored on Maglev’s servers; interview transcripts may be processed by an AI provider.

Continue with from files to a quote request.

Check your connection

Section titled “Check your connection”
Terminal window
maglev doctor
maglev doctor --json

Available in hosted CLI 0.6.14. The command does not install dependencies, change login, modify configuration, read project files or create API records.

Check Evidence Limits
Node.js Running version meets 22.13 or later An incompatible runtime may fail to launch the CLI before diagnostics can run
API GET /health responds with the expected healthy status The endpoint currently includes a database read; this is not a test of every operation or provider
Login GET /me accepts the selected credential and returns its expected mode Scopes are permissions, not approval for a specific recipient, disclosure, purchase or production run

MAGLEV_API_KEY takes precedence over a saved login, including an empty or stale value. The report identifies the source as environment, saved_login or none, without showing the key. MAGLEV_API_URL selects the API profile.

Each request has a five-second deadline and a 64 KiB response limit. --timeout 10000 changes the deadline to ten seconds per request, capped at thirty seconds. Redirects are refused. There is no automatic retry. At most two GET requests are made; a missing or invalid local key skips the authenticated request.

connectionStatus: "connected" means the runtime, health and login checks passed. externalActions.status remains not_checked: provider setup, file grants, disclosure approval, supplier replies, quote acceptance and production are checked in their own workflows. The command does not trust the health endpoint’s interviewer label as provider evidence, run a model, send a test email or issue a replacement key.

Exit Meaning Next step
0 Connection checks passed Continue the intended workflow and review its permissions and result
2 Runtime or local configuration problem Follow the reported runtime/API URL/private-profile guidance
3 Missing, malformed or rejected credential Check the environment override and key expiry/revocation; use maglev login when appropriate
5 Network, service, rate limit or unexpected response Check the API URL, connectivity and service status; retain the request ID

When several checks fail, local configuration takes precedence, followed by the API failure, then authentication. Read the individual checks, not only the exit code. A rejected key does not prove an account suspension.

Terminal window
maglev doctor --json > maglev-connection.json

The report includes the CLI/runtime versions, API origin, check statuses, bounded timing, recognized scopes, key mode/expiry and a request ID when present. It omits key values, account names, custom API paths, arbitrary response bodies and project data. Inspect any report before sharing it if your API hostname is private. Never share ~/.maglev, environment dumps or recovery files instead. This diagnostic concerns the Maglev connection; it does not repair a disconnected ChatGPT/Codex response stream.

For interrupted writes, first read the saved interview, action or delivery receipt. A failed connection check is not a reason to repeat a manufacturing action.

Other ways to connect

Section titled “Other ways to connect”
Connection Use it when Status
CLI Your agent has a shell, or you want terminal scripts Available as a versioned Maglev download
HTTP API Your application or agent can send HTTPS and JSON Available; see the API reference
Local MCP server Your client can run a stdio MCP process Current MCP: 45 manufacturing tools. Native connector 0.1.6 includes those tools plus two connection tools
Agent skill Your agent can read instructions and use one of the above Available at SKILL.md
Local fixtures You want the real CLI without an account or key Available; synthetic data only
Hosted HTTP/OAuth MCP Your client requires a remote MCP URL Not available
Native CAD plug-in You expect Maglev to read a SolidWorks model directly Not available

A terminal-only installer is also published:

Terminal window
npx -y --package=https://trymaglev.com/assets/connect/maglev-connect-0.1.6.tgz maglev-connect --agent codex

Use claude for Claude Code or openclaw for its configured workspace. Connector 0.1.6 pins CLI 0.6.14 and MCP 0.2.14, including supplier replies, bounded quote waiting, action observation and original-key recovery. App launch alone does not prove connection: check get_identity or maglev auth check --json.

If connection is interrupted

Section titled “If connection is interrupted”

Rerun the same installer. It resumes pending approval, reuses a valid saved account, and recovers an expired saved or interrupted-approval credential through fresh browser approval. Your agent can add --no-browser on a remote host to show the approval URL and matching code, or run the same package with maglev-connect --help for offline help.

A failure includes a code and next step. environment_key_rejected means MAGLEV_API_KEY overrides saved login and was rejected. Decide whether to keep that configured account or run the installer without the override to use browser sign-in. Never print or paste the key. Network errors and permission denials preserve saved connection state.

If a pending request cannot resume, the same package supports maglev-connect --cancel to cancel it while preserving the previous saved login. Then rerun setup. If your agent host blocks execution, use its approval controls for the blocked command; Maglev does not change host permission settings.

If something does not fit

Section titled “If something does not fit”
  • Your agent cannot run shell commands: use the “Any other agent” block, which falls back to HTTPS against the API.
  • Your key expired: run maglev login again, or maglev login --sandbox for examples. Browser live keys last ninety days; sandbox keys last one day. A pending interrupted login resumes instead of creating another key.
  • You already have a Maglev skill: preserve custom instructions. Use the managed project upgrade for recognized originals; review custom files locally rather than deleting them.
  • A newly configured MCP host may need to reload its settings; check an actual tool response before treating the tools as loaded.
  • For an interview conflict, empty shortlist or interrupted write, see errors and limits.

Upgrade through the same installer

Section titled “Upgrade through the same installer”

Connector 0.1.6 supports automatic use of the managed project upgrade for recognized original Claude Code and Codex installations. It checks the expected API address and both files before sign-in, then applies the recoverable update only after account connection succeeds. Changed files, custom instructions and different API targets stop for local review. A pending final upgrade record is completed even if both files were written before interruption.

This version pins CLI 0.6.14 and MCP 0.2.14 and includes 45 manufacturing tools plus two connection tools. Earlier connector archives remain available unchanged. This does not add automatic Hermes/OpenClaw configuration migration or prove that a native host reloaded its tools.