Run an unpublished Assistant through your Local Team

Check the complete project first

Fix the first reported error before continuing. This check validates the source package and generated machine contract; it does not install or publish anything.

Let staging translate your messages

Every shimpz.text message, the manifest summary and description, each Action description, and each Stored Input label are English. To show them in each person's interface language, save your own OpenAI API key in the file ~/.config/shimpz/openai-api-key ($XDG_CONFIG_HOME/shimpz/openai-api-key when that variable is set, or %APPDATA%\shimpz\openai-api-key on Windows), readable only by you, for example with chmod 600. On Windows the CLI does not check the file's permissions, so keep it in your private profile.

Staging then sends only the English text of each new or changed message to OpenAI, never source code, Action input, or parameter values, and remembers every admitted translation in the CLI cache, so an unchanged message is not translated again while its remembered translation stays valid. The provider bills your key. Without the file, staging still works and every interface language shows your English text; staging tells you so.

Build one exact snapshot in your Docker daemon

The values inside angle brackets vary. Save the complete sha256: image ID: it is the immutable identity you will authorize. To stage a different working directory, run shimpz assistant stage --project /path/to/assistant.

A successful stage tags the image as this Assistant's current snapshot, shimpz-local/<assistant_id>:staged, in the host Docker daemon. Repeating the command for unchanged source reuses the current snapshot; changed source uses the layer cache and produces a new image ID that becomes current. Only the current snapshot can be installed.

Staging contacts no Shimpz service and needs no sign-in. It copies the language pack read-only into the image after every stage that runs Assistant code, and the Language line reports whether the messages were translated or stay in English. Team then shows each request in the Supervisor's interface language when the messages were translated, and in English when they were not.

Let chat install a fresh binding automatically

1. Open the exact Local Admin address that shimpz install or shimpz status prints, such as http://127.0.0.1:7777; the port depends on your installation.
2. Sign in as Supervisor and complete the required TOTP factor.
3. Open the destination Team and request work that strongly matches an Action declared by the staged Assistant.
4. Watch the installation card. Chat captures the exact primary image on the server, Team fully admits it, and a fresh binding is installed without another install prompt.

If the same assistant_id is both staged locally and published, Local discovery uses only the staged candidate on this machine. A Local-only identity is eligible too. Team admits the exact image's embedded manifest, contract, source package, icon, platform, capability labels, and runtime before it starts the workload. A failed install does not authorize a partial snapshot, does not switch to the published release, and does not dispatch the original task.

Automatic installation is fresh-only. If this Team already has that Assistant installed—from Store or Local—the chat task does not replace it or delete its Integration and Stored Input state. Open Assistants, find the card marked LOCAL, select Install or replace, compare the complete image ID in the unpublished-code dialog, and confirm the destructive transition explicitly. A Team holds at most 16 Assistants, so Team refuses a fresh install into a full Team.

Use the same Action path as an installed Assistant

After every planned Assistant is running and its required Integrations are configured, chat dispatches the original request once. Verify the Team's complete response and the external result when the Action has one. Normal egress, Action validation, human requests, audit, Integrations, and Stored Input boundaries apply after admission.

Staging never asks for provider access. An OAuth Integration is configured only when its Action needs it. A declared Stored Input—such as a WhatsApp token—is requested just in time and retained under that Team's custody instead of being requested on every run.

Restage changed source, then replace deliberately

1. Edit the Assistant and rerun shimpz assistant check.
2. Run shimpz assistant stage and record the new image ID.
3. Reload the Assistants page in Admin, compare that ID in the install dialog, and select Install or replace.
4. Exercise the changed Action again through the Team.

After a successful Local replacement, the earlier snapshot is no longer current, and the running Local Space removes it once no Team binds or runs it. If the successor fails, the current binding keeps its image and the newly staged snapshot stays current, so you can inspect or retry it.

Keep snapshots after uninstall, or remove them explicitly

Uninstalling the Local Assistant removes Team-owned workload, binding, egress, icon, Integration, Stored Input, continuation, and audit state. It keeps this Assistant's current snapshot staged on this machine, so chat can install it again without rebuilding it. While the Local Space runs, it removes each earlier snapshot once no Team binds or runs it. Published Assistant images remain lifecycle-managed by Team because an immutable Store release can be resolved again.

First uninstall this Assistant from every Team, then run shimpz assistant unstage from its project. Add --project /path/to/assistant to select another working directory. The command removes the current snapshot and any earlier one that remains: every image that has both the exact current Local-stage label and this project's exact assistant_id. It never uses force or parent pruning, and Docker refuses removal while a container still references an image. Finding no matching snapshot is already success.

Permanent removal means you must run shimpz assistant stage before using that Local Assistant again. Shimpz never runs a global Docker image prune, because unrelated projects and another retained snapshot may share layers. Do not run a global Docker image prune manually.

Keep the snapshot in its one Local boundary

Stage reports that a message could not be translated

Shorten or simplify the shimpz.text copy so every translation fits its field, then stage again. Messages already translated are not sent again.

Stage reports a problem with the OpenAI key or provider

Replace the key or fix the file's ownership and permissions, wait and stage again when the provider limited or was unavailable, or remove the key file to stage with English text.

The snapshot does not appear in Admin

Confirm the CLI used the same machine and Docker daemon as the Local Space, then rerun shimpz assistant stage and reload snapshots. Local fails closed instead of truncating when more than 50 Assistants have a current snapshot; run shimpz assistant unstage from unused Assistant projects and retry.

The exact image is missing after staging

Restage the trusted source. Team never pulls a replacement for a Local image.

You need another Space, Store discovery, or distribution

Publish a separate immutable release through Developers. Local staging needs no publication, Store listing, or Neuron operation, and its language-pack preparation sends only the English message catalog. It creates none of their distribution or trust evidence.