Tama Kit

Tama Kit is a domain-neutral ChatGPT and Codex plugin for bootstrapping applications with Tama and building, changing, and auditing Tama Terraform graph networks. It combines guided CLI and application-integration skills, focused graph skills, and a workspace-specific Tama MCP connection. The skills cover standard bootstrap, MCP App OAuth provisioning, routed conversations, direct forwarded actions, shared replies, ingestion, enrichment, embeddings, indexing, batch reprocessing, the required global foundation, and Terraform-safe graph migration.

Bootstrap a local Tama runtime

Tama Kit also ships a conventional CLI for adding a local Tama runtime and a starter Terraform root to an existing Rails, Phoenix, Node, or generic application repository:

npx @kritama/tama-kit bootstrap

After a global npm installation, the equivalent command is:

tama-kit bootstrap

In an interactive terminal, bootstrap asks which project and setup mode to use, resolves Compose ambiguity, and collects only the relevant settings. Choose a standard local runtime or an MCP App OAuth provider integration. Suggested values come from the project, provider contract, and saved configuration. Advanced settings include images, contracts, provider identity, and migrations.

Before any write, review the image, ports, public identities, skills, and file changes. Choose to prepare files, start services, or explicitly activate a ready MCP App integration. Type :back to revisit a configuration step or :cancel to exit. EOF and Ctrl-C also pause setup. Dry runs remain read-only.

After generation, use tama-kit setup to start and verify current configuration or tama-kit doctor for read-only diagnosis. The interactive bootstrap rerun offers these next steps. It does not refresh files or change saved settings. Existing files or receipts do not prove runtime health or Terraform provisioning.

Flags remain available for automation and advanced callers:

npx @kritama/tama-kit bootstrap --non-interactive --skills manual --dry-run
npx @kritama/tama-kit bootstrap --skills local --dry-run --json

JSON and non-TTY invocations never prompt; --non-interactive disables all questions even in a terminal. These modes default to manual skill installation unless an explicit flag selects local skills during initial generation. JSON output includes non-secret setup phases and next-action identifiers.

Bootstrap creates private runtime files under tama/, adds project-owned Tama and PostgreSQL services, and generates a Terraform root with focused agent guidance. It preserves the owned global foundation and refuses ambiguous ownership. It does not require a separate Tama source checkout. Terminal colors and progress remain available; use --no-color to disable styling.

After a successful write, bootstrap ends with a copy-ready coding-agent prompt. The prompt starts and checks the local Compose runtime, guides the user through the private browser setup without exposing credentials, runs Terraform initialization, formatting, validation, and planning, and requires explicit approval before terraform apply. Human output includes the complete private onboarding URL with its setup token so it can be opened or copied into the agent prompt. If the user explicitly requests guided setup and in-app browser control is available, the agent opens the URL there; otherwise it follows the local README instructions. Treat that URL as a secret. JSON output exposes a token-redacted version as agentPrompt; dry-run output sets it to null.

All generated files are developer-owned immediately, including Terraform, Compose, contracts, examples, instructions and copied skills. Edit them directly. The optional version-2 tama/.tama-kit.json receipt contains provenance and incomplete-generation progress only; no permanent content hashes or desired configuration. Completed reruns preserve customized and deleted output. Legacy version-1 manifests are accepted as history without comparing file hashes. Use --resume <operation-id> with the original options only for an explicitly unfinished generation; existing output is preserved.

Setup and doctor read the native Compose model, environment bindings, current contract and Terraform source without consulting receipts. For custom layouts, select repeatable --compose roots/overrides, --service, --proxy-service, --env-file, --contract, --provider-service, and --ca-file. Doctor accepts --terraform-root and reports uninitialized providers without running init. setup --dry-run --json previews without writes or startup; doctor --runtime adds probes of existing services. Current inspection requires Compose's native config --format json --no-env-resolution support. Older Compose releases that discard declarations use a native model-rendering fallback for literal environment file paths; interpolated paths require a newer Compose release. Native Docker Compose and Terraform commands remain usable without Tama Kit or any receipt.

Inspect the proposed changes without writing:

npx @kritama/tama-kit bootstrap --dry-run

Generate and start the local services:

npx @kritama/tama-kit bootstrap --start

Add MCP App to an existing standard project

Use the dedicated capability generator:

npx @kritama/tama-kit generate mcp-app --provider-name my-app \
  --image ghcr.io/upmaru/tama:0.13.2-server --dry-run --json

Remove --dry-run to write the reviewed additions. It reads current Compose configuration, preserves existing runtime keys and Terraform, and creates tama/compose.mcp-app.yaml, a separate private tama/.mcp-app.env, the provider fragment, local bridge contract, and tama/MCP_APP.md. Only missing secret-ignore entries are appended to existing integration files. An existing pinned compatible image is reused; a floating tag or custom build requires an explicit --image.

For custom layouts, select ordered --compose files, --service, and --env-file. Follow the emitted setup and native Docker commands: they append the generated Compose override to your existing selection. Local HTTPS uses Caddy, a derived CA image, and an atomic private certificate/key bundle under tama/mcp-app-tls/. The override clears Tama's old published ports and requires Compose 2.24.4+. Even its dry run requires the Compose CLI for current configuration inspection; no daemon is needed. Generation never starts the provider or activates either side.

The separate tama/.tama-kit-mcp-app.json receipt records this operation only. Completed reruns preserve changes and deletions. Use --resume <id> with the original options only for an unfinished addition. Use setup for subsequent activation and verification; provider loading, CA trust, and restarts remain application-owned. See tama/MCP_APP.md for the exact handoff.

Bootstrap an MCP App provider integration

Use --mcp-app from the provider application's repository. Contract-aware providers can commit priv/contracts/tama-mcp-app-bootstrap-v1.json; other providers must supply an explicit name. Fresh integrations use local HTTPS, derive the exact provider and Tama origins, default the client origin to the provider, and select the pinned compatible 0.13.2-server image:

npx @kritama/tama-kit bootstrap --mcp-app \
  --provider-name acme \
  --install-local-ca

Choose a concrete pinned image version in the intersection of Tama Kit's bundled range >= 0.13.2 and < 0.14.0 and the application-owned contract's supported_tama_versions when that contract is present. Versioned official images use the <version>-server tag form; latest remains unsuffixed. If no provider range is declared, 0.13.2-server is a valid default. Do not use 0.13.2-server when the provider contract excludes version 0.13.2.

The default public identities are https://app.localhost and https://tama.app.localhost; Caddy connects privately to the host-native provider through host.docker.internal and to Tama through the Compose network. Those transport names are never OAuth identities. The provider application remains responsible for listening on the selected private port and using the generated public issuer; Tama Kit does not add provider-specific proxy or listener controls. Allowed client origins may use HTTP only on loopback; every non-loopback allowed origin must use HTTPS. Supply at most 32 unique allowed origins. A custom non-.localhost name additionally requires --acknowledge-local-domain-risk after its local DNS behavior is verified.

Initial generation also writes tama/contracts/mcp-app-provider-v1.json, a non-secret local contract that normalizes provider identity, exact environment bindings, public endpoint paths, source provenance, and environment-loader evidence before either owner's environment file is planned. Providers without a committed contract use conventional bindings immediately; this local artifact does not claim the provider runtime implements the OAuth protocol. Application-owned contracts under priv/contracts/ are only read, never generated or modified.

For an application-owned provider service in the root Compose file, select its service name and private container port:

npx @kritama/tama-kit bootstrap --mcp-app \
  --provider-name acme --provider-service acme --provider-port 4000

This selects the Compose provider runtime. Caddy reaches http://acme:4000 and depends on the service's health check when one is declared. Public OAuth origins remain the HTTPS names above. The application owns its service, Dockerfile, development mode, and provider environment loading; the selected service must load the reported tama/ integration fragment and share the default Compose network. Services declared only through extends, includes, or optional profiles are not currently supported as provider selections.

To change an existing topology, edit the project-owned Compose, proxy, certificates, contracts and environment bindings directly. Preserve keys, review identities, then use doctor and setup to inspect and verify the change. Bootstrap migration flags no longer upgrade existing projects.

Activation is deliberately two-step:

npx @kritama/tama-kit setup --activate

The first run verifies prepared state and enables/restarts Tama, then reports the provider-owned mode change. Set the reported provider mode variable to enabled, restart the provider, and rerun the same command. Tama Kit reports an enabled state only after both live services pass metadata, JWKS, introspection, protected-resource, route, and direct Tama-container reachability probes. It never executes provider lifecycle commands. See MCP App provider bootstrap for the contract, secret ownership, rerun, and recovery rules.

Activation edits only Tama's safely identified mode assignment. It never rewrites environment fragments or changes provider mode. A failure during an already-enabled check preserves configuration. Recovery after its own mode change restores that assignment while preserving unrelated developer edits.

The first release uses Tama's supported interactive setup flow to create root and provisioner credentials. Bootstrap does not use the test-only provisioner path and never runs terraform apply.

Prepare a Tama source checkout

Tama contributors can prepare a newly cloned Tama repository with:

npx @kritama/tama-kit dev setup

This command is intentionally separate from bootstrap. It generates a private .envrc, starts only the pgvector PostgreSQL service declared by Tama's repository-owned compose.yml, waits for the container to become healthy, runs mix setup, and provisions Tama's test foundation. It installs only the OpenTofu version declared by the checkout when foundation provisioning is required, that tool is missing, and mise is available. It also maintains repository ignore rules for the generated credentials before writing them. It does not install or use a host PostgreSQL. Phoenix remains a native host process. Native Phoenix listens on 127.0.0.1:4001 by default. Development and test database connections use loopback port 55432 by default, so they do not select a PostgreSQL server listening on the host's standard 5432 port. The generated environment also bounds local ExUnit concurrency so high-core development machines do not overwhelm the container.

Choose another native Phoenix or isolated PostgreSQL loopback port when necessary:

npx @kritama/tama-kit dev setup --port 4567
npx @kritama/tama-kit dev setup --postgres-port 55433

To generate the private files without starting Docker or running Mix, use --prepare-only. Use --dry-run or --json for a secret-free plan. Existing secrets and an existing Tama port are preserved on every rerun. Passing --port updates only the native Phoenix PORT export; changing the PostgreSQL port updates only the development and test database port exports. For the canonical Memovee integration topology, use:

npx @kritama/tama-kit dev setup --port 4001 --postgres-port 55432 --json

Generate a staging OAuth key

For environments that bootstrap does not manage, such as a staging deployment whose configuration lives in a secret manager, generate the same System OAuth signing key pair standalone:

tama-kit oauth generate-key --kid staging-2026-09-01-1 --stdout

The command works without a Tama checkout, Mix, or Docker and requires exactly one destination. With --stdout it prints exactly two dotenv assignments and nothing else:

TAMA_OAUTH_PRIVATE_JWK='{"alg":"RS256","kid":"staging-2026-09-01-1",...}'
TAMA_OAUTH_PRIVATE_JWK_ID=staging-2026-09-01-1

--kid is optional; when omitted, the identifier is derived from the public-key thumbprint. Explicit identifiers accept ASCII letters, digits, dots, underscores, tildes, and hyphens so the emitted assignments remain portable dotenv syntax. Paste each value into the staging environment, or create an owner-only file for transfer with --output:

mkdir -p "$HOME/tama-oauth-transfer"
chmod 700 "$HOME/tama-oauth-transfer"
tama-kit oauth generate-key --kid staging-2026-09-01-1 \
  --output "$HOME/tama-oauth-transfer/staging.env"

--output resolves relative paths against the current working directory, creates the file exclusively with mode 0600, and prints only the resulting path. It refuses existing files, symbolic links, missing or unwritable parent directories, directories owned by another user, and directories that are group- or world-writable without the sticky bit (root-owned sticky directories such as /tmp remain usable because other users cannot rename entries there, and the directory owner can rename entries even in a sticky directory). Paths inside a Git worktree must be ignored and untracked. Requiring a private parent directory means another user cannot exchange the path between validation and the write, so the reported path is the file that was created. It never edits .gitignore and never replaces an existing file, so rotating the signing key always uses an explicit new destination.

Installation

Codex

Tama Kit is distributed as a plugin containing tama-kit-cli, app-integration, graph-builder, and graph-audit. The plugin is downloaded from npm through the Upmaru marketplace; installing the npm package by itself does not enable the plugin in ChatGPT or Codex.

This installation path requires the Codex CLI with plugin support, Node.js 20.12 or newer, and an npm CLI available on your system.

Add the marketplace and install the plugin:

codex plugin marketplace add kritama/tama-kit
codex plugin add tama-kit@upmaru

Start a new Codex session after installation so Codex can load the bundled skills. You can then invoke any skill explicitly:

$graph-builder
$graph-audit
$tama-kit-cli
$app-integration

For example:

Use $tama-kit-cli to help me bootstrap my app to work with Tama.

The skill first asks whether the application is an MCP App provider so it can choose between ordinary bootstrap and the contract-aware --mcp-app workflow. For an MCP App, it then classifies the provider as OAuth-ready, partial, or absent. When OAuth is absent, it explains that an application-side OAuth 2.1 provider integration is a prerequisite and asks before expanding the work; Tama Kit configuration alone does not make the application a provider. For graph work:

Use $graph-builder to add a routed support-search component with plain and
artifact replies, then verify every trigger-to-terminal path.

To confirm the plugin is installed:

codex plugin list

OpenCode

OpenCode loads Agent Skills directly; it does not use the Codex plugin manifest. Install all Tama Kit skills globally with the Skills CLI:

npx skills add kritama/tama-kit \
  --agent opencode \
  --global \
  --yes

For a project-only installation, run the same command from the project root without --global:

npx skills add kritama/tama-kit \
  --agent opencode \
  --yes

Start a new OpenCode session after installation, then ask it to use tama-kit-cli, app-integration, graph-builder, or graph-audit. You may install an individual skill with --skill <name>. These steps install only the skills; configure your workspace-specific Tama MCP server separately when runtime inspection is needed. See the Skills CLI, OpenCode's official Agent Skills, and MCP servers documentation.

Included skills

tama-kit-cli selects and runs the appropriate CLI workflow for an ordinary application, MCP App provider, Tama source checkout, or standalone OAuth key. For an ambiguous application bootstrap request, it first asks whether the app is an MCP App provider before choosing flags.

app-integration implements and provisions the application-owned OAuth authorization server for Tama's exact /mcp/app protected resource. For setup requests it first validates the Tama Kit bootstrap artifacts and generated local contract, then verifies whether existing OAuth is ready, partial, or absent, preserves provider/Tama key custody, implements the disabled/prepared/enabled lifecycle when authorized, and verifies the staged activation handoff.

graph-builder designs, implements, extends, migrates, and removes graph slices. It models execution edges, control edges, operational policy, terminals, and Terraform lifecycle impact before editing.

graph-audit traces existing graphs without editing them. It reports incomplete topology, missing control edges, unsafe lifecycle changes, and runtime unknowns with exact evidence.

Development

The bundled maintenance utilities and Terraform inspector are dependency-free Node.js ES modules; no Python runtime is required. The CLI combines checked JavaScript with TypeScript contracts and workflows. Run npm ci and npm run build before invoking node bin/tama-kit.mjs directly. The build checks the mixed source tree, then emits .mjs files beside .mts sources. Generated counterparts are ignored by Git; edit the .mts source files.

npm test, npm pack, and the runtime validation commands build automatically. Run npm run validate:package to verify the tarball in an isolated consumer. The published package contains ready-to-run ESM and its templates, contracts, and skills; installed users need neither TypeScript nor a build step.

Command input/output lives in cli/commands and cli/output, execution in cli/workflows, typed domain contracts in cli/domain, and reusable system operations in cli/shared. Bootstrap and source-development policy remain in cli/bootstrap and cli/dev. See the cleanup design for compatibility and recovery boundaries.

Memovee-derived forward-test cases live in evals/cases.json; public skill references remain domain-neutral. Validate the public-directory metadata, Template MCP scaffold, and review cases with:

npm run check
npm run typecheck
npm test
npm run validate:bootstrap
npm run validate:submission

npm run check verifies formatting, lint rules, and import ordering with Biome. Use npm run check:fix to apply its safe fixes and formatter output locally.

The public Template MCP connection is intentionally not represented by a fake local endpoint. Configure the review materials with a concrete, working example endpoint:

npm run configure:mcp -- \
  --example-url "$TAMA_KIT_EXAMPLE_MCP_URL"

The example URL must be publicly reachable and must match the committed https://{host}/mcp template. Tama deployments expose Streamable HTTP at /mcp; their OAuth discovery metadata remains owned by each deployment. The OpenAI Platform draft identifier shown as asdk_app_v_... belongs to the draft URL and is not an MCP app ID, package setting, or .app.json value.

After configuration, run the review-readiness gate and build the distributable plugin ZIP:

npm run validate:review
npm run build:submission

The archive is written to dist/tama-kit-<version>.zip. In the OpenAI Platform draft, enter the Example and Template MCP Server URLs directly and upload the final skill bundles from skills/. Portal test cases remain in evals/cases.json because they are review materials rather than plugin runtime files. Copy-ready listing URLs, selected review cases, and release notes live in submission/portal.json.

Template MCP URLs are available only to trusted OpenAI developers with an established relationship. The OpenAI review also requires a verified publisher, Apps Management write access, and a public non-test example MCP endpoint. See the official plugin packaging and submission requirements.

License

Tama Kit is licensed under the Apache License 2.0.