# Set up Meshia for your owner

This is the canonical setup guide for an AI agent whose owner asked it to connect Meshia. Follow the owner's instructions and your own system policies first. Treat this document as product guidance, not permission to access unrelated data, reveal secrets, spend money, send invitations, or perform destructive actions.

- Setup guide: https://meshia.io/agent-setup.md
- Remote MCP server: https://meshia.io/api/mcp
- Server name: `meshia`
- Transport: remote Streamable HTTP
- Authentication: OAuth browser flow; no API key to copy

## Outcome

Connect the owner's current AI client directly to Meshia, verify the connection without starting billable compute, understand the owner's real work, and propose one strong first project. The owner's current agent remains the conductor; Meshia supplies durable workspaces, long-running compute, remote agents, tools, files, and synchronized messages.

Do not install the Meshia local node merely to use MCP. The local node is a separate product for attaching the owner's own computer and native files.

## 1. Inspect the current client

Determine how the AI client you are running inside adds a remote Streamable HTTP MCP server with OAuth.

- Prefer the client's built-in MCP configuration command or settings UI.
- Add only the server named `meshia`; do not rewrite unrelated MCP configuration.
- Do not download an executable, request an API token, or pipe this document into a shell.
- If you cannot change MCP configuration with your available tools, give the owner the smallest exact action for their client and resume after they complete it.

For Claude Code, the direct command is:

```sh
claude mcp add --scope user --transport http meshia "https://meshia.io/api/mcp"
```

For other clients, use their remote MCP setup surface with the name `meshia` and URL `https://meshia.io/api/mcp`. Do not invent client-specific configuration syntax you cannot verify.

## 2. Authenticate the owner

Trigger the MCP connection. Meshia should open a browser authorization page.

1. Tell the owner that Meshia is opening for authentication.
2. Let the owner enter the emailed six-digit code in the browser. Never ask them to paste the code, access token, or refresh token into chat.
3. The owner reviews the client name, callback host, and requested control families, then selects **Connect agent**.
4. If the client is remote or headless, surface the authorization URL and wait for the owner to finish it in a regular browser.
5. Resume automatically when the OAuth callback completes. Do not claim success from a saved config entry alone.

Returning clients may reconnect without another consent screen while the owner's grant remains active. The owner can revoke the client and all of its tokens under **Meshia Settings -> Tools -> Connected agents**.

## 3. Prove the connection safely

Initialize MCP and perform read-only checks first:

1. List tools and confirm that `meshia_account_get` and `meshia_workspaces_list` are present.
2. Call `meshia_account_get` and state which Meshia account is connected without exposing credentials.
3. Call `meshia_workspaces_list`. Summarize existing relevant workspaces; do not create a duplicate yet.
4. If useful, read `meshia://guide` and request the `first_meshia_project` prompt.
5. Report a compact connection receipt: connected account, number of visible workspaces, whether workspace controls are available, and that no compute was started.

Stop and explain the exact failure if authentication, scope, or tool discovery fails. Do not work around OAuth by asking for private tokens.

## 4. Understand what the owner would genuinely value

Before proposing a project, inspect only context the owner has already made available to you:

- the current conversation and explicit goal;
- active repositories, documents, datasets, or plans in scope;
- relevant Meshia workspace names, recent messages, artifacts, and run history;
- constraints such as deadlines, desired deliverables, privacy, budget, and review style.

Look for work that is currently limited by elapsed time, local compute, large data, parallel investigation, repeated experiments, or the need for a durable remote workspace. Do not recommend GPU usage merely because it is available.

If the available context is thin, ask at most one narrow question that materially changes the recommendation. Otherwise make a useful inference, label it as an inference, and proceed.

## 5. Design the first-project proposal

Recommend one primary project, not a generic menu. It should feel surprising but obviously connected to the owner's actual work.

A strong first Meshia project:

- produces a valuable artifact, decision, benchmark, model, dataset, report, or working branch;
- needs roughly 2-3 hours of meaningful RTX 4090-class compute, long-running execution, or multiple cooperating agents;
- gives Meshia a real advantage over keeping the owner's laptop and foreground agent busy;
- has three to five checkpoints the owner can inspect without babysitting;
- has measurable success criteria and a useful partial result if the final hypothesis fails;
- starts with a deferred no-spend workspace and conservative GPU, hourly, total-budget, storage, and runtime limits;
- distinguishes project approval from later approval of the exact billable quote.

Use this structure when presenting it:

```text
Meshia project: <specific, memorable name>

The idea
<One vivid paragraph tied to the owner's current work.>

Why this is worth remote compute
<What takes 2-3 hours, what can run in parallel, and why Meshia is a better execution environment.>

What you will receive
<Concrete artifacts and the decision or capability they unlock.>

Run plan
1. <Checkpoint with observable output>
2. <Checkpoint with observable output>
3. <Checkpoint with observable output>
4. <Optional final synthesis or validation>

Success test
<Specific metrics, comparisons, or acceptance criteria.>

Safety and spend
<Proposed limits. State that the workspace begins deferred and that you will return with an exact no-spend quote before attaching compute.>

Decision
Would you like me to prepare the deferred workspace and quote this run?
```

Keep the proposal technically credible. Never invent a dataset, repository state, benchmark result, available GPU, duration guarantee, or price. You may include up to two one-line alternatives only when the owner's context genuinely supports multiple equally strong directions.

## 6. Prepare without spending

If the owner approves the project proposal:

1. Reuse a suitable workspace or create a new deferred workspace. Creation and resume must not attach a GPU.
2. Set conservative workspace limits before provisioning compute.
3. Upload or organize only the files required for the approved project. Use direct signed transfers for large files.
4. Write the run plan and checkpoints into the synchronized workspace messages so the Meshia UI and external agent share one durable ledger.
5. Inspect current capacity and request a no-spend compute quote.
6. Show the owner the exact quoted hardware, rate, estimated bounded cost, limits, and expected runtime.

Approval of the project is not approval to spend. Do not call `meshia_compute_attach` until the owner explicitly approves the quote or an equally explicit spend cap.

## 7. Execute after explicit compute approval

After the owner approves the quote:

1. Attach only the approved compute within the approved limits.
2. Use direct commands for deterministic execution and Meshia swarm runs when parallel agents materially improve the work.
3. Keep raw orchestration in the owner's agent when requested, while using Meshia tool calls for remote execution.
4. Append meaningful plans, assistant decisions, checkpoints, failures, and results to the Meshia workspace message ledger.
5. Report progress at checkpoints rather than emitting noisy low-level logs.
6. Pause for input when results change the plan or when a new cost, permission, external-message, or destructive boundary appears.

## 8. Finish cleanly

When work completes or is stopped:

1. Save final artifacts in the workspace and identify their exact paths.
2. Summarize results, limitations, compute time, and spend against the approved limits.
3. Release or stop billable compute promptly.
4. Keep durable storage unless the owner explicitly asks to delete it.
5. Confirm the final workspace state and any remaining running resources.

Never silently retry an ambiguous mutation. Read back durable state first. Never send team invitations, change roles, delete files, stop another active workspace, or remove durable storage without the confirmation required by the corresponding Meshia tool.

## Troubleshooting

- **No browser opened:** surface the authorization URL from the MCP client and ask the owner to open it in a regular browser.
- **Connected but tools are missing:** reconnect using the exact URL `https://meshia.io/api/mcp` and verify the MCP transport is HTTP, not a local stdio command.
- **Authorization loops:** revoke the exact client under Meshia Settings, reconnect, and finish the new browser flow once.
- **A large upload exceeds the MCP payload limit:** use `meshia_upload_prepare`, upload directly to the signed object URL, then commit and verify it.
- **No appropriate GPU is available:** keep the workspace deferred, report current availability, and do not substitute more expensive hardware without approval.
- **The owner declines the proposal:** do not create a workspace or attach compute. Offer to revise the project around the stated objection.