How it works

You put a secret in the safe. A crew member asks for the use of it, and the First Mate or you grant it until a set time. A crew member never sees the value, and nothing in the ship's log, on the Bridge or in a crew tool's answer shows one.

A crew member with a grant is given a stand-in: a text with no meaning outside the Ship. When the crew member sends it to a host the secret is bound to, the egress gateway puts the real value in its place on the way out. The value is never in the crew container.

A stand-in works only for its crew member, only for the hosts and in the way the secret says, and only until its grant ends.

Adding a secret

On the Safe page, under "Add a secret", give:

• Name: lower-case letters, digits and hyphens, at most 64 characters, one of a kind in the safe.
• Description: one line, at most 200 characters. The crew and the First Mate read it.
• Value: from 1 byte to 16 KiB.

Press Add secret. The value is stored encrypted and never shown again, to you or to anyone.

Saying where it opens

A secret can be used only where you say. Edit uses opens a form of up to eight uses. Each is a host and the way the stand-in is sent there:

• Bearer token: sent as Authorization: Bearer followed by the stand-in. Other one-word schemes work too, except basic, digest, negotiate and ntlm.
• The password of basic auth: what Git over HTTPS wants.

A secret is sent to one host as a bearer token or as basic auth, not both. A secret that a host needs both ways is added twice, under two names.

For example, a GitHub token can open api.github.com as a bearer token, for the API, and github.com as the password of basic auth, for Git over HTTPS.

Granting use

A crew member asks with its request_secret tool, saying what the secret is for and for how long. The First Mate decides, or you, on the Approvals page or the Safe page. You can also grant directly, without a request, under "Grant directly": a crew member, a secret, what it is for, and Hours from 1 to 720 or Until revoked.

A crew member has at most one grant for a secret, and a new one replaces it. A grant ends:

• at its end time, counted from the moment it is granted;
• when you or the First Mate revoke it, with an optional reason;
• when its secret is removed or its value replaced.

Changing and removing

• Replace value sets a new value and ends every grant of the secret, since the new value may open other things. It asks first when a grant would end.
• Edit description changes the description.
• Remove asks first, then deletes the value and ends its grants. The value cannot be brought back.

MCP servers that need a sign-in

A crew member can reach an MCP server outside the Ship through the Helm, which adds the server's sign-in to the call, so no key is in a container. The sign-in is a secret of the safe.

1. On the Safe page, add the secret: its name, a description and the server's token as the value.
2. On the Extensions page, once the server is allowed, press Choose the secret on its row, pick the secret and press Save.
3. A crew member that calls the server is told which secret it needs and asks for it. The First Mate or you grant it, and its next call works.

Revoke a grant on the Safe page and that crew member's next call fails again.

If you find a secret in the open

A secret belongs in the safe and nowhere else: not in a cabin, a logbook or a chat. A commit that would add one to the Ship's history is refused, and the nightly push to GitHub is scanned for secrets first. A crew member that finds one in the open tells the Captain.