App access
share_app, set_app_access, list_app_access and revoke_app_access — controlling who is allowed to open a deployed app.
These tools control who can open a deployed app. That is a different thing from
invite_user, which grants a person control over the agenthost account
itself. An invitee here gets to load the running app and nothing else.
An app is locked one of three ways:
| Mode | Who gets in | How they prove it |
|---|---|---|
| public | anyone with the link | nothing to prove |
| invite-only | addresses you have invited | a one-time code, emailed to them |
| password protected | anyone you gave the password to | typing that password |
Invite-only is the stronger of the two locks and the one that can name and un-name people individually. Password protection is the lighter one, for when you would rather hand a preview to a room than collect everyone's address. Both put the same gate in front of the app, so a visitor with nothing sees a page instead of your content either way.
share_app
Give a specific person access to an app by email. This switches the app to invite-only: once shared, only invited addresses can open it and everyone else is turned away at a sign-in screen.
| Parameter | Type | Description |
|---|---|---|
service_id | uuid, required | App (service) id. |
email | string, required | Email address to grant access to. |
name | string | Optional display name for the invitee. |
Call it once per person; re-sharing the same address is a harmless no-op. The invitee is emailed a link to the app — when email is not configured on the server, the result hands you the link to share yourself instead.
The invite comes from you, not from agenthost: your name in their inbox, an address belonging to your account, and a reply that lands with you. The message itself is plain, and so is the sign-in screen it leads to, with only a single line at the foot naming where the app is hosted. Your client sees the app you shared, not our brand.
The first share flips the switch
An app that was public becomes invite-only the moment you share it with anyone, and so does one
that was password protected. Use set_app_access to put it back.
set_app_access
Set which of the three locks an app is behind.
| Parameter | Type | Description |
|---|---|---|
service_id | uuid, required | App (service) id. |
access | "public", "invite" or "password", required | Who gets in, per the table above. |
password | string | Only for access: "password". The password to set. Omit to keep the app's existing one, or to have one generated. |
Switching modes throws nothing away. The invitation list survives a spell of password protection and the password survives a spell of invite-only, so an app that is opened up for a launch and closed again afterwards comes back to exactly what it had before.
Re-issuing the mode an app already has re-locks it, which is worth doing if you suspect a deploy left it reachable.
Setting a password
Ask for access: "password" and either give the password you want or leave it out and get one back:
"password protect the staging site"
→ Harbour Bookings is now PASSWORD PROTECTED.
The password is: k7mq-p2xr-9vftThat is the only time you will ever see it. agenthost stores a hash of the password and nothing more, so it cannot be read back to you later. Write it down, or ask your agent to keep it somewhere you will find it.
Setting a password again replaces the old one and immediately shuts out everyone who was using it, including anyone with the app already open. That is how you take access back, since there is no list to remove a person from.
It is one shared secret
Password protection keeps your app off the open web and out of search results. It does not tell you who is looking, and it is only as private as the people you gave it to. When you need to know who opened something, or to remove one person without disturbing everyone else, use invite-only.
list_app_access
Show how an app is locked and, when invite-only, everyone who has been given access — including whether each person has actually opened it.
| Parameter | Type | Description |
|---|---|---|
service_id | uuid, required | App (service) id. |
An invite-only app with an empty list is reachable by nobody, and the result says so. For a password-protected app the result says when the password was last set, never what it is.
revoke_app_access
Remove one person's access to an invite-only app. It takes effect immediately, even if they were already signed in. The app stays invite-only for everyone else.
| Parameter | Type | Description |
|---|---|---|
service_id | uuid, required | App (service) id. |
email | string, required | Email address to remove. |
Private apps are a paid feature
Putting the gate in front of an app — share_app, or set_app_access with invite or password
— needs a plan that includes private apps; get_plan says whether this account has one. Making an
app public is never gated, so an account that loses the feature can still open its apps up, and
an app that is already private stays private in the meantime.