# Developing with Takumi Agent {#development}

On a Mac with [Takumi Agent](/docs/t/endpoint/index.md), package installs go through Takumi Guard without any configuration. What you will notice is the **device certificate**: every program that downloads from a supported registry has to trust it. This page covers where that is handled for you and where you need to do something.

A program that doesn't trust the device certificate is **blocked, not bypassed**. Its download never reaches the registry, so the Mac stays protected. The install just fails until you fix the program.

## After installing: restart terminals and IDEs {#restart}

Takumi Agent sets up certificate trust for shells and apps started after setup. Programs that were already running keep their old environment. After installing:

- **Open a new terminal window.** Tabs and windows opened before setup don't have the settings.
- **Quit and reopen your IDE and any AI coding agent** that was running (VS Code, Cursor, JetBrains IDEs, Claude Code and so on). Their built-in terminals inherit the app's environment, so a new tab inside an old IDE isn't enough.
- **Restart background services** you started yourself, such as a local build server.

## Tools on the Mac {#host-tools}

Go uses the macOS keychain, so it trusts the device certificate with no setup. For the common tools that use their own certificate store, Takumi Agent sets these environment variables for every shell and app:

| Variable              | Used by                                   |
| --------------------- | ----------------------------------------- |
| `NODE_EXTRA_CA_CERTS` | node, npm, npx, yarn, pnpm, corepack, bun |
| `REQUESTS_CA_BUNDLE`  | python, pip, pipx, poetry, pdm, conda     |
| `SSL_CERT_FILE`       | ruby, CocoaPods, uv, curl, wget           |
| `GEMRC`               | gem, bundler                              |
| `PHP_INI_SCAN_DIR`    | php, composer                             |

The values are set in `/etc/takumi-agent-endpoint/env.sh`, which the system shell startup files load. The certificates are in the trust bundle at `/Library/Application Support/takumi-agent-endpoint-trust/bundle.pem`.

**deno** has its own certificate store, which Takumi Agent doesn't configure yet. Set `DENO_TLS_CA_STORE=system` to make it use the macOS keychain.

:::note If you set these variables yourself
If your own startup file sets one of these variables to something else (for example `export NODE_EXTRA_CA_CERTS=…` in `~/.zshrc`), it overrides the agent's value, and tools started from that shell stop trusting the device certificate. The panel tells you which file. Remove the line, or set the variable to the value in `/etc/takumi-agent-endpoint/env.sh`.
:::

## Containers and VMs {#containers}

**Docker Desktop, OrbStack and Rancher Desktop** trust the device certificate with no setup, because they read the macOS keychain when they start. If one was already running when Takumi Agent was set up, or when the device certificate last changed, quit and reopen it. Restarting a single machine inside it isn't enough (for OrbStack, run `orb stop` and then `orb start`). The panel and the Containers page show which runtime needs this.

Runtimes that run their own VM (Colima, Lima, Podman, Multipass, minikube) need the Containers page's setup command once, which installs the bundle in the VM and restarts it. For a full virtual machine (vfkit, UTM, Parallels, VMware Fusion, VirtualBox, QEMU), you manage the guest system yourself, so the page builds a command to paste inside the guest. **Apple Container** (the `container` command) doesn't read the keychain and can't be given a custom certificate yet, so it can't trust the device certificate.

**Installing packages inside a container** needs one more step. Every image has its own trust store, so `npm install` or `pip install` inside a container rejects the device certificate until you give the container the bundle. [The app window's Containers page](/docs/t/endpoint/features/app-window.md#containers) gives you a snippet for each way of starting containers.

### Keep the setup out of your repository {#keep-out-of-repo}

The trust bundle only exists on Macs with Takumi Agent. CI runners and teammates without the agent don't have the file, so **keep container trust setup on your machine, not in files your team commits**:

| You start containers with | Do this                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docker run`              | Pass the mount and the variables on the command line. To shorten the command, put the variables in an env file outside the repository (`--env-file ~/.takumi/container.env`). The mount (`-v`) still goes on the command line.                                                                                                                     |
| Docker Compose            | Put the snippet in an override file next to your Compose file (`compose.override.yaml`) and rename its `app` service to yours. Compose only merges it when you run `docker compose` without `-f`. If you pass `-f`, or the repository already commits an override file, add yours with an extra `-f`. Keep it out of git with `.git/info/exclude`. |
| `docker build`            | See [Building images on the Mac](#docker-build).                                                                                                                                                                                                                                                                                                   |

Docker Desktop doesn't share `/Library` by default, so the bundle's folder (`/Library/Application Support/takumi-agent-endpoint-trust`) also has to be listed under **Settings › Resources › File sharing** for the mount to work. The Containers page reads Docker's settings and tells you whether it is.

### Building images on the Mac {#docker-build}

A `RUN npm install` inside `docker build` also needs the certificate, and this is the hardest place to keep the setup out of your code. You have two options.

**Keep it local.** The Containers page's Dockerfile snippet copies the bundle in through a named build context:

```dockerfile
# docker build --build-context takumi="/Library/Application Support/takumi-agent-endpoint-trust" .
COPY --from=takumi bundle.pem /takumi/trust.pem
ENV SSL_CERT_FILE=/takumi/trust.pem
ENV NODE_EXTRA_CA_CERTS=/takumi/trust.pem
ENV REQUESTS_CA_BUNDLE=/takumi/trust.pem
```

The `takumi` build context only exists on your Mac, so a Dockerfile with these lines won't build in CI or for teammates without Takumi Agent. Only use it in an uncommitted copy of the Dockerfile, and only in a builder stage. Otherwise the `ENV` lines end up in the final image.

**Commit something that does nothing elsewhere.** BuildKit skips a secret mount when the secret isn't passed, so the same Dockerfile builds everywhere:

```dockerfile
RUN --mount=type=secret,id=takumi,target=/takumi/trust.pem \
    if [ -f /takumi/trust.pem ]; then \
      export SSL_CERT_FILE=/takumi/trust.pem NODE_EXTRA_CA_CERTS=/takumi/trust.pem REQUESTS_CA_BUNDLE=/takumi/trust.pem; \
    fi; \
    npm ci
```

On your Mac, build with `docker build --secret id=takumi,src="/Library/Application Support/takumi-agent-endpoint-trust/bundle.pem" .`. In CI and on other machines, build as usual. The certificate never ends up in an image layer. This still adds Takumi-specific lines to a shared file, so agree on it with your team first.

## Registry credentials and publishing {#credentials}

Takumi Guard decides installs. Takumi Agent sends every install request on a supported package registry (package metadata and the packages themselves) to Guard, using your organization's Guard token instead of your own registry credentials. Everything else works as it does without the agent: `npm publish`, `gem push`, `npm login`, `npm deprecate`, `npm owner` and other account operations go to the registry with your own credentials, and the registries' websites, APIs and vulnerability lookups such as `pip-audit` and `composer audit` are answered by the registry itself.

One thing doesn't work through the agent: installing a private package hosted on a public registry, such as a private package on `registry.npmjs.org`. That install reaches Guard with your organization's token instead of yours, so the registry refuses it. Install those packages from CI, which doesn't run the agent, or host them on a private registry, which the agent doesn't capture.

## When the panel names a program {#panel-messages}

When a program doesn't trust the device certificate, the menu-bar panel names it. [Troubleshooting](/docs/t/endpoint/references/troubleshooting.md#panel-messages) lists each message and its fix.