# Deploy an existing adapter

Use a context-only adapter first: it needs no dataset, service, or model calls to generate a host workspace.
Deployment writes files the acting host will read; it does not start the host.

## 1. Prepare an adapter

From the repository root:

```bash
mkdir -p .demo
cp -R hermit/algorithms/templates/prompt_only .demo/deploy-adapter
python -c 'from pathlib import Path; Path(".demo/deploy-adapter/ADAPTER.md").write_text("# Working rules\n\nCheck units before doing arithmetic.\n")'
python -m hermit.spec .demo/deploy-adapter --root hermit/algorithms/templates/prompt_only
```

Use a fresh destination for the copy. You can instead use a trained `<run>/checkout/` with its compatible template.

## 2. Generate and inspect a workspace

```bash
hermit deploy --adapter .demo/deploy-adapter --workspace .demo/deploy-codex --host codex
cat .demo/deploy-codex/AGENTS.md
cat .demo/deploy-codex/.codex/config.toml
```

`AGENTS.md` should contain the units rule in a managed adapter block. This adapter has no tools or roles, so the
report's `server` is null and the configuration contains no adapter MCP entry.

The workspace must be empty or already generated by the framework for the same host, and separate from the
adapter directory. An arbitrary nonempty project is refused. Within an existing generated workspace, redeployment
replaces generated host configuration and the managed context block; do not store hand-written settings in
generated files you expect to keep unchanged.

## 3. Update and redeploy

```bash
python -c 'from pathlib import Path; Path(".demo/deploy-adapter/ADAPTER.md").write_text("# Working rules\n\nCheck units and dates before doing arithmetic.\n")'
hermit deploy --adapter .demo/deploy-adapter --workspace .demo/deploy-codex --host codex
cat .demo/deploy-codex/AGENTS.md
```

The managed block should now contain units **and dates**, with no duplicate adapter block.
If Codex is installed and authenticated, start it separately:

```bash
cd .demo/deploy-codex
codex
```

Return to the repository root for the remaining commands. For Claude Code use a separate destination and
`--host claude-code`; inspect its `CLAUDE.md`. Host installation and actual model calls are outside file generation.

## 4. Convert to a native plugin

From the repository root, this context-only adapter can be converted for Claude Code:

```bash
hermit convert --adapter .demo/deploy-adapter --output .demo/deploy-plugin --target claude-code
python -c 'from pathlib import Path; print("\n".join(str(p) for p in sorted(Path(".demo/deploy-plugin").rglob("*")) if p.is_file()))'
```

Inspect the conversion JSON and the emitted marketplace/plugin files. Conversion embeds the adapter and produces
a package to install using the [target's plugin commands](../framework/commands.md#install); it does not install
or enable the plugin. Native plugin targets have different export capabilities. For example, a nonempty context
is refused for Codex and Pi conversion; workspace deployment is a different route.

Do not use `--allow-lossy` just to make a refusal disappear: check whether omitting the reported export would
remove the behavior you intend to ship. See the [capability matrix](../framework/commands.md#what-each-hosts-plugin-carries).

## Tools, roles, and services

`docs/_examples/file_adapter/` demonstrates roles, skills, and a simple `count_words` tool.
Tool adapters require the framework and their dependencies in the Python environment where the generated tool
server runs. Workspace tool configuration uses absolute source paths; keep that adapter directory available.

The [Lean collaboration adapter](../recipes/lean-collaboration.md) additionally needs a running team service,
Lean/Mathlib, and per-agent settings. Follow its complete recipe before starting hosts; generating workspace
files alone does not make the team service available.

To assess whether a deployed adapter helps a different acting host, run an appropriate
[evaluation](../guides/evaluation.md). File generation is not a performance measurement.