# embed

> Put your agent inside your app, for each signed-in user.

Put Bash inside your own app, for the user who is signed in. One iframe gives your user chat, approvals, Bash's live screen and voice. Your server opens a session, a short-lived link for that user, and your page shows its url.

## TypeScript

```ts
// Open a session on your server. Do this for the user signed in to your app. It gives them chat, approvals,
// the live screen and voice.
const session = await vestra.user('traveller-42').embed();
// Put session.url in an iframe on your page: <iframe src={session.url} allow="microphone" />
console.log(session.url, session.expires_at);

// Show the memory panel. Your company must turn it on first.
const withMemory = await vestra.user('traveller-42').embed({ memory: true });

// End the session. Its token stops working at once.
await withMemory.end();
```

## Python

```python
# Open a session on your server. Do this for the user signed in to your app. It gives them chat, approvals,
# the live screen and voice.
session = vestra.user("traveller-42").embed()
# Put session.url in an iframe on your page: <iframe src="{{ session.url }}" allow="microphone"></iframe>
print(session.url, session.expires_at)

# Show the memory panel. Your company must turn it on first.
with_memory = vestra.user("traveller-42").embed(memory=True)

# End the session. Its token stops working at once.
with_memory.end()
```

## CLI

```bash
# Preview what your users see. It opens chat, approvals, the live screen and voice. In your app, open one
# session per visit on your server, with the SDK or over HTTP.
vestra embed --user traveller-42

# Show the memory panel. Your company must turn it on first.
vestra embed --user traveller-42 --memory
```

## HTTP

```bash
# Open a session on your server. Do this for the user signed in to your app. It gives them chat, approvals,
# the live screen and voice. The response has a url and a token, valid for 15 minutes. Put the url in an
# iframe with allow="microphone".
curl "$VESTRA_BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $VESTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "traveller-42", "chat": true, "screen": "view", "voice": true }'

# Check the session. See whether it is still open.
curl "$VESTRA_BASE_URL/v1/sessions/ses_8h2" \
  -H "Authorization: Bearer $VESTRA_API_KEY"

# End the session. Its token stops working at once.
curl -X DELETE "$VESTRA_BASE_URL/v1/sessions/ses_8h2" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

## MCP

```json
{
  "method": "tools/call",
  "params": {
    "name": "embed",
    "arguments": { "user": "traveller-42", "memory": true }
  }
}
```

## Good to know

### What the session token can see

A session's token lasts 15 minutes and can only reach that user and the session's conversation. It never shows what anything costs, never lists interactions, and never sees calls to your tools.

### Which sites can show it

Your company's `allowed_embed_origins` setting decides which of your sites may show a session in an iframe. With none set, the session still works as a page of its own.

### Ending a session

`DELETE /v1/sessions/{id}` ends a session at once. Its token stops working, its streams close, and a `session.ended` event says so.

## The routes behind embed

- `POST` [/v1/sessions](https://vestra.ai/developers/reference/api/sessions/post-v1-sessions.md): Open a session for one of your users (user_id), or for the company's own Bash: chat, a screen to watch or drive, a voice call, and what Bash remembers (memory, when your company turned the panel on). Answers a 15 minute token for the user's browser, a ready page url and the sites allowed to frame it. The token reaches only that user, and only the session's conversation. Key scope: `runtime` (or `all`).
- `GET` [/v1/sessions/{session_id}](https://vestra.ai/developers/reference/api/sessions/get-v1-sessions-session-id.md): Whether a session is still open, and what it was opened with. Your key, or the session's own token. Key scope: `runtime` (or `all`).
- `DELETE` [/v1/sessions/{session_id}](https://vestra.ai/developers/reference/api/sessions/delete-v1-sessions-session-id.md): End a session now: its token stops working, its streams close and its call hangs up. Your key, or the session's own token. Key scope: `runtime` (or `all`).
- `GET` [/v1/sessions/{session_id}/frame-policy](https://vestra.ai/developers/reference/api/sessions/get-v1-sessions-session-id-frame-policy.md): Which sites may show a session's page. The page asks this itself; you never need to.

Next: [`users`](https://vestra.ai/developers/users.md)