Start a tool with everything in place

Outcome and prerequisites

You will open a coding tool that has memory, the folder's scoped credentials, and the right project root from its first turn — and confirm that your machine is exactly as it was afterwards. synapse launch wires a tool for the life of one process. It is not a setup step and it writes nothing into the tool's own configuration.

• The synapse CLI installed and on PATH.
• Codex, Claude Code, or pi installed. None of them needs to be connected — that is the point of this tutorial.
• A scratch project folder. Steps four and five create a disposable vault value.

1. Preview before you launch

   Work in a scratch folder so nothing here touches a real project:

   shell Copy

   mkdir -p "$HOME/tmp/launchtutorial" && cd "$HOME/tmp/launchtutorial"
   git init --quiet .
   synapse launch claude --print

   --print resolves everything and shows you the result instead of running it:

   text Copy

   /Users/example/.local/bin/claude --mcp-config ~/Library/Application Support/synapse/relay/launch.66c4a25fcfe8.mcp.json
   env  SYNAPSE_PROJECT_DIR=/Users/example/tmp/launchtutorial

   Try Codex too. It reads no MCP configuration file, so it gets the server on its command line instead:

   shell Copy

   synapse launch codex --print

   text Copy

   /Users/example/.asdf/shims/codex -c mcp_servers.synapse.command="/Users/example/.local/bin/synapse" -c mcp_servers.synapse.args=["mcp"]
   env  SYNAPSE_PROJECT_DIR=/Users/example/tmp/launchtutorial

2. Read what it actually did

   Three things were resolved, and each is worth understanding before you trust the command with a real project.

   Piece	Where it came from
   The program	Looked up in the registry of connectable tools, then on PATH. A tool that is not installed fails here with a name, not a shell error.
   The MCP wiring	Written only because this tool has no Synapse connection of its own. A connected tool is launched as-is and gets no generated file at all.
   SYNAPSE_PROJECT_DIR	The folder you launched from, walked up to its project root. This is what scopes the tool's memory and, on the mesh, its registration.

   The generated configuration is keyed on a digest of the project root, so relaunching in the same folder reuses one file rather than accumulating them. Look at it if you like — it names this binary and the mcp argument, and nothing else.

3. Add scoped credentials

   A launched tool can run a shell, so it gets the same scoped environment synapse run would give a child. Create a disposable value and map it to this folder:

   shell Copy

   synapse vault create demo
   synapse secret set demo token DEMO_TOKEN

   Enter a throwaway value at the hidden prompt. Then create the scope and approve it:

   shell Copy

   synapse scope init .

   yaml Copy

   version: 1
   scope: project
   env:
     DEMO_TOKEN: demo.token
   deny: []

   shell Copy

   synapse allow
   synapse launch claude --print

   The preview now names the variable and refuses to show what is in it:

   text Copy

   /Users/example/.local/bin/claude --mcp-config …/launch.66c4a25fcfe8.mcp.json
   env  SYNAPSE_PROJECT_DIR=/Users/example/tmp/launchtutorial
   env  DEMO_TOKEN=<from the vault>

   <from the vault> is not a redaction applied to a value that was read. A preview calls a different code path that lists names and never opens the vault at all, so there is no value in the process to leak.

4. Watch it refuse a half-resolved environment

   Break the scope's approval by editing the file — a blank line is enough, because approval is bound to the exact bytes:

   shell Copy

   echo "" >> .synapse.yaml
   synapse status .

   text Copy

   Folder: .
   Available: none
   Ambient: blocked
   /Users/example/tmp/launchtutorial/.synapse.yaml [project · pending]
   warning: /Users/example/tmp/launchtutorial/.synapse.yaml: Scope has not been approved

   Now try to launch:

   shell Copy

   synapse launch claude --print

   text Copy

   Error: vault scope is not ready:
   /Users/example/tmp/launchtutorial/.synapse.yaml: Scope has not been approved

   It refuses rather than starting the tool with DEMO_TOKEN missing. That is deliberate and it is the same rule synapse run applies: a tool that can run a shell is never handed a partly-resolved environment, because the failure mode is a command that runs against the wrong thing and looks like it worked.

   Read the changed file, then approve it again:

   shell Copy

   synapse scope status .
   synapse allow
   synapse launch claude --print

5. Pass the tool its own flags

   Everything after a bare -- reaches the tool untouched:

   shell Copy

   synapse launch claude --print -- --resume --model opus

   text Copy

   /Users/example/.local/bin/claude --mcp-config …/launch.66c4a25fcfe8.mcp.json --resume --model opus
   env  SYNAPSE_PROJECT_DIR=/Users/example/tmp/launchtutorial
   env  DEMO_TOKEN=<from the vault>

   The split happens before Synapse parses anything, which is why a flag both programs understand still reaches the right one. Without that, a --model meant for the tool would be eaten by Synapse.

6. Launch for real

   shell Copy

   synapse launch claude

   The tool opens as it normally would. Ask it what Synapse tools it has; the answer should include remember, recall, and vaultstatus. Ask it to call vaultstatus and it will report DEMO_TOKEN as available — the name only, because that tool returns metadata and cannot read the value.

   If this is Claude Code and it is also connected, its first message will carry this project's memory; see Session start. A launched tool that is not connected has the MCP tools but not the session hook, because the hook lives in that tool's own settings and launching writes nothing there.

   Exit the tool. Then confirm the machine is unchanged:

   shell Copy

   synapse status

   The tool's own configuration was never opened. Nothing needs undoing.

Clean up

synapse deny
synapse secret forget demo.token
synapse vault delete demo
cd .. && rm -rf launchtutorial

Forgetting the secret removes the stored value and Synapse's record of it. The generated MCP configuration under the data folder is harmless — it names this binary and nothing else — and is overwritten on the next launch in the same folder.

What you can rely on

• Launching never edits the tool's own configuration. Making a connection permanent is synapse connect, a separate decision.
• A preview prints variable names and never a value, because it never reads one.
• Any scope warning refuses the launch outright rather than starting the tool with part of its environment.
• A connected tool is launched as-is. The generated configuration exists only for a tool that has no connection of its own.

Next step

Continue to Run a team of agents and drive it yourself, which uses the same launch pipeline to open several tools at once and put you on the roster with them.