# Agent & Tools
Source: https://docs.alkera.ai/foundations/agent-and-tools
How the agent works: effects, permission modes, approvals, and the tools it acts through.
The Alkera agent works on your organization's data. A wrong change there is quiet and expensive, so the agent is built around one idea: reads are cheap, and anything that changes state has to earn its way through.
## Tools
The agent acts only through tools. It can:
* **Query data**: run SQL against your [connections](/foundations/plugins-and-connections) and read table and column schemas.
* **Work with files and code**: read and edit files in the workspace and run shell commands on its [machine](/workspaces/machines).
* **Build notebooks**: create and edit [notebooks](/notebooks/overview), run cells, and show outputs in the chat.
* **Use knowledge**: search and read the [knowledge base](/foundations/knowledge-base), and record what it learns.
* **Use lineage**: trace how an asset is produced and what depends on it with [lineage](/foundations/lineage).
Every tool call is classified by its [effect](#effects) and passes the same [permission gate](#permission-modes), so the rules below hold whether the agent is running SQL, a shell command, or a notebook cell.
## Effects
Every action is classified by its effect before it runs. When the agent asks for approval, the card tells you which effect it has.
| Effect | Meaning | Examples |
| - | - | - |
| **Read** | Only reads files or data | `SELECT`, `ls`, reading a schema |
| **Write** | May change files or data | Editing a file, `INSERT`, `UPDATE` with a `WHERE` |
| **Destroy** | May delete files or data | `rm`, `DELETE`, `DROP TABLE` |
| **Egress** | May send or fetch data over the network | Fetching a URL, copying data to an external stage |
| **Exec** | May run programs on the database server | Calling a stored procedure |
| **Memory** | May change what the agent remembers | Recording a knowledge entry |
SQL is parsed into a syntax tree, so the effect is taken from every statement in it. A `DELETE` hidden inside a CTE is still a delete. Shell commands are parsed the same way, including pipelines and subshells.
## Permission modes
The mode decides what happens when the agent reaches an action that is not a read. Pick it in the composer, or press Shift + Tab to cycle.
| Mode | Behavior |
| - | - |
| **Read-only** | Reads freely, writes only in this chat, and runs no shell. |
| **Plan** | Explores, writes only in the chat's files, and proposes a plan for you to approve. |
| **Default** | Runs reads freely and asks before changes outside the chat's files. |
| **Auto** | Works on its own and pauses only for risky or destructive steps. |
| **Bypass permissions** | Runs everything without asking. Opt in deliberately. |
Your starting mode for new chats is your saved default. Only people who can edit a chat can change its mode.
## Approving actions
When the agent is gated, it shows an approval card with what it wants to do and why. You can:
* **Allow once**: run it this time.
* **Reject once**: refuse it this time. The agent adapts and continues.
* **Always allow**: save a rule so the same kind of action passes next time.
* **Always reject**: save a rule so it is refused next time.
"Always" rules are deliberately narrow:
* For most shell commands, a rule covers the command family. Allowing `ls -la` also allows `ls src`.
* A destructive command is remembered only as its exact text, offered as **Always allow this exact command**.
* No standing rule is offered for commands whose meaning depends on what they expand to when they run.
* Rules apply to the mode you answered in, and belong to you. Only the chat's owner can save one.
## Large results
A query that returns thousands of rows should not be pasted into a conversation. It would cost a fortune in tokens, bury the reasoning, and force the agent to read numbers one by one.
So when a result is larger than 50 rows or 64 KiB, Alkera stores it as a **result** and gives the agent a handle and a small preview. The agent can check its shape and columns, profile it, filter and sort it, and run read-only SQL over it in place. Querying a large result can produce a smaller one, so the agent can narrow a result step by step.
Open **Results** in the chat to see every result it produced. Each one pages through the full data and can be downloaded.
## What the agent reads first
Before it changes anything, the agent grounds itself in two things.
* **[Knowledge](/foundations/knowledge-base)** tells it what your data means and what your team already decided. It reads the knowledge base before it plans, and records what it learns.
* **[Lineage](/foundations/lineage)** tells it how your data is produced. It uses lineage to find what a change would break downstream.
## Related
Where you work with the agent.
The data the agent can reach.
What your data means, and what your team decided about it.
How your data is produced, and what breaks if you change it.
# Knowledge Base
Source: https://docs.alkera.ai/foundations/knowledge-base
Your organization's shared memory: what the data means, and what your team already decided about it.
Schemas tell you what columns exist. Your team knows far more than that: what a metric means, which table is the source of truth, and which join quietly duplicates rows. The knowledge base holds that knowledge.
The [agent](/foundations/agent-and-tools) reads it before it answers, and writes to it as it learns. Open it from **Knowledge** in the sidebar.
## Entries
Each entry is one piece of knowledge.
| Kind | What it holds |
| - | - |
| **Note** | Conventions, decisions, and context in your own words. |
| **Fact** | A specific claim about your data, often learned by the agent. |
| **Query** | Reference SQL: the right way to compute something. |
| **Schema** | A description of a table or view and its columns. |
### Add an entry
Click **Add entry** and fill in:
* **Title** and **Kind**.
* **Statement**: the knowledge itself.
* **Applies to**: a repository, or **Entire org**.
* **Filed under**: a subject path that groups related entries, such as `glossary/net_revenue` or `conventions/sql`.
* **Filed on a lineage node**: attach the entry to a table or column so it travels with that asset.
## Trust
Every entry shows who wrote it and whether anyone has confirmed it.
| Trust | Meaning |
| - | - |
| **Verified** | A person on the team confirmed it. |
| **Agent-set** | The agent asserted it, and no person has confirmed it yet. |
| **Unverified** | Nobody has confirmed this claim. |
Entries also show their origin: written by a **Human**, recorded by the **Agent**, or pulled from a **Connector**.
The agent weighs trust rather than treating every entry as equally true. Knowledge the agent records starts out unverified. To confirm an entry you own, click **Verify**.
## Visibility
An entry is **Private** to you until you share it. Check **Share with the team** when you add or edit it to make it visible to your **Team**, or **Org-wide**.
* Private entries are visible only to you and your chats.
* **Hide for me** hides a teammate's entry from you and from your agent, without removing it for anyone else.
### Knowledge sync
Sharing knowledge requires **Knowledge sync** to be on for the organization. An organization admin turns it on in **Settings**, under **Knowledge sync**. While it is off, entries stay private.
## How the agent uses it
* **Before it plans**, the agent searches the knowledge base for anything related to the request, such as definitions, conventions, and reference queries.
* **As it learns**, it records new facts, marked as set by the agent so a person can review and verify them. Recording knowledge is a **Memory** [effect](/foundations/agent-and-tools#effects).
* **When it is wrong**, correct the entry or ask the agent to. Your correction is used in every chat after that.
## Related
How the agent reads and writes knowledge.
The structural counterpart: how your data is produced.
# Data Lineage
Source: https://docs.alkera.ai/foundations/lineage
The graph of how your data is produced, and how the agent uses it to check what a change would break.
Alkera keeps a lineage graph of the data your [connections](/foundations/plugins-and-connections) reach: which tables produce which, and which columns feed which. The [agent](/foundations/agent-and-tools) reads this graph to answer the question that matters before a change lands: what breaks if I touch this?
**A browsable lineage view is coming soon.** Today, ask the agent about lineage in a chat, such as "What feeds `analytics.revenue`?" or "What breaks if I drop `orders.discount_code`?"
## Grains
Lineage is recorded at two grains.
* **Table grain.** A table or view is produced from other tables.
* **Column grain.** A column is produced from other columns, tagged with how it was derived, such as a rename, a cast, an aggregate, or a join key.
Column lineage comes from parsing the SQL that builds a view or model. Where that is not possible, Alkera falls back to the table grain rather than guessing.
## Certainty
Every edge records how directly the flow was observed, from weakest to strongest.
| Tier | Where it comes from |
| - | - |
| **Inferred** | A best guess, for example from naming |
| **Declared** | A tool's own metadata, such as a foreign key or a dbt `ref` |
| **Parsed** | Read out of the SQL that builds the asset |
| **Observed** | Seen running in query history |
A connection can never claim an edge stronger than its access justifies. A connection that cannot read query history never produces an observed edge. When the agent reports lineage, it says how each edge was observed, so you can treat it as evidence rather than proof.
## Where it comes from
Lineage is built from your connections, not from what the agent did last turn. Alkera reads table and view definitions, and query history where the connection allows it. Alkera builds the table grain first, then fills in column lineage.
## Blast radius
Before a change such as dropping a column, renaming one, changing its type, or dropping a table, the agent pushes the change through the column graph and classifies the result:
* **Breaking.** Something downstream depends on what you are removing.
* **Potentially breaking.** A dependency exists, but Alkera cannot prove it breaks.
* **Non-breaking.** Nothing downstream in the paths it checked depends on it.
It reports the affected downstream assets with the verdict, which also tells you which checks are worth rerunning.
## Lineage and knowledge
[Knowledge base](/foundations/knowledge-base) entries can be filed on a lineage node, such as a table or a column. The meaning of an asset, its gotchas, and how it is produced stay together, and the agent finds them all when it works with that asset.
## Related
How the agent uses lineage before it changes anything.
What your data means, attached to the assets it describes.
# Plugins & Connections
Source: https://docs.alkera.ai/foundations/plugins-and-connections
Connect your warehouses and databases, and control who can use each connection.
A **plugin** is an integration type, such as Snowflake or PostgreSQL. A **connection** is one instance of it, such as your production Snowflake account. One plugin can hold many connections.
The agent and your [notebooks](/notebooks/sql-and-python) work with the data your connections reach.
## Available plugins
| Plugin | Kind | Sign in with |
| - | - | - |
| **Snowflake** | Data warehouse | Programmatic access token, username and password, or browser sign-in (OAuth) |
| **BigQuery** | Data warehouse | Browser sign-in (OAuth) |
| **Databricks** | Lakehouse | Personal access token, or browser sign-in (OAuth) |
| **Amazon Redshift** | Data warehouse | Host, database, user, and password |
| **PostgreSQL** | Database | Host, database, user, and password, with optional TLS |
| **MySQL** | Database | Host, database, user, and password |
| **ClickHouse** | Analytics database | Host, database, and user |
| **Trino** | Query engine | Host, catalog, and user |
| **Apache Druid** | Analytics database | Router URL, with optional HTTP basic authentication |
| **Tinybird** | Analytics database | API host and a workspace token |
| **Elasticsearch** | Search engine | URL, with an API key, a bearer token, or a username and password |
| **MongoDB** | Document database | Connection string, with optional username and password |
| **Apache Kafka** | Streaming | Bootstrap servers and service credentials, with optional Schema Registry and Kafka Connect |
| **dbt** | Transformation | A dbt project folder |
| **Airflow** | Orchestration | Base URL and an API token |
| **AWS** | Cloud | IAM Identity Center (SSO) |
| **Generic SQL** | Any SQLAlchemy database | A [SQLAlchemy database URL](https://docs.sqlalchemy.org/en/20/core/engines.html) |
Notebooks also include **DuckDB**, which needs no connection. Use it to query files and the notebook's own dataframes.
Curious about an integration we do not support? Email [contact@alkera.ai](mailto:contact@alkera.ai). We would love to hear what you want to connect, and it may already be on our roadmap.
Need Alkera to reach a system that is not listed here, or one built in-house? We build custom integrations for enterprise plans.
## Add a connection
Click **Connections** in the sidebar, then **Add connection**.
Under **Who this connection is for**, choose **Just me** for a personal connection, or a team to share it with everyone on that team. Only team admins can add team connections.
Pick the plugin and how to sign in, and fill in its details.
Every connection also needs a **Deployment tier**: **Production**, **Staging**, **Development**, or **Local**. It tells the agent how careful to be.
Click **Save connection**. Alkera checks the connection first and saves it only if the check passes.
## Personal and team connections
| | Personal | Team |
| - | - | - |
| Belongs to | You | A team |
| Who can use it | You | Every member of the team |
| Who manages it | You | The team's admins |
A team connection can work in one of two ways:
* **One shared login.** The admin enters the credentials once, and everyone on the team uses them. Members never see the secret.
* **Each member signs in.** With browser sign-in (OAuth), each member signs in through their browser, so their own warehouse permissions apply.
The **Connections** page groups connections under **Yours**, your organization's, and each team's.
**Sharing a workspace lends your connections.** People you [share a workspace](/workspaces/overview#sharing) with can query data through your connections from its chats while they have edit access.
## Credentials
Credentials are stored on Alkera's servers, never in your workspace files and never in the agent's context.
Alkera connects to your systems as the connection's user. Whatever roles and grants your warehouse enforces still apply.
## Status and upkeep
Each connection shows its status, such as **Connected** with when it was last verified, **Sign in again**, **Update credential**, **Unreachable**, or **No access**.
From a connection's menu, you can:
* **Verify now** to check it again.
* **Edit…** to change its settings or credentials.
* **Remove…** to delete it. Removing a team connection removes it for all members.
## Related
How the agent uses your connections, and what it may do with them.
Query a connection from a notebook.
# Get access
Source: https://docs.alkera.ai/get-access
Create an Alkera account, join your organization, and sign in.
Alkera is a web app at [app.alkera.ai](https://app.alkera.ai). There is nothing to install. Open it in a current desktop browser.
**IDE extensions and a CLI are coming soon.** They will work with the same workspaces and chats as the web app, and let you run workspaces locally on your own machine.
## Create an account
Go to [app.alkera.ai/signup](https://app.alkera.ai/signup) and enter your email and a password of at least 12 characters. You can also continue with **Google** or **GitHub**.
Use your work email so teammates can find your organization.
Enter your first and last name, and a name for your **organization**. Signing up without an invitation creates a new organization and makes you its first [admin](/organization/teams#roles).
Click the link in the verification email. Until you verify, you cannot chat with the agent or invite teammates. If the email does not arrive, click **Send verification email** in the banner at the top of the app.
Unverified accounts lose access after seven days.
You land on **Overview**, your organization's home page. From there, follow the [Quickstart](/quickstart).
## Join your organization
If your organization already uses Alkera, ask an admin to [invite you](/organization/teams#invitations). Signing up on your own creates a separate organization.
Open the link in the invitation email and set a password, or click **Accept invitation** if you are already signed in. If you already belong to another organization, you join this one too and can [switch between them](/organization/teams#multiple-organizations). Invitations expire after seven days. If yours has expired, ask for a new one.
## Sign in
Sign in at [app.alkera.ai/login](https://app.alkera.ai/login) with your email and password, Google, or GitHub. Your organization may turn off some of these methods or require [single sign-on](/organization/teams#single-sign-on).
To add two-factor authentication, open the account menu at the bottom of the sidebar, choose **Profile**, and set it up under **Two-factor authentication** with an authenticator app. Save your backup codes when they are shown, because they are shown once.
## Self-hosted deployment
Alkera can run on your own infrastructure if your data cannot leave it.
Deploy Alkera into your VPC, or onto hardware you own. Air-gapped installs are supported, and self-hosted deployments can use your own model provider keys.
Self-hosted, VPC, and air-gapped installs are available on enterprise plans.
## Next steps
Connect a warehouse, ask the agent a question, and build a notebook.
# Overview
Source: https://docs.alkera.ai/index
What Alkera is, how its pieces fit together, and where it runs.
Alkera is a platform for data engineering, analysis, and data science, where your team and an AI agent work on your organization's data together.
You describe what you want in a chat. The agent queries your warehouses, writes and runs code, and builds notebooks in a workspace your teammates can open alongside you. It proposes before it changes anything, and you stay in control of what runs.
## Why Alkera
Coding agents were built for software, not data. Code that runs without errors can still be wrong: a bad join, a silent sample, or a stale source produces output that looks right and is not.
Alkera grounds the agent's work in how your data actually flows and what it means:
* **Knowledge base.** A shared record of your business definitions, conventions, and reference queries. The agent reads it before it answers and records what it learns.
* **Lineage.** How each table and column is produced, so the agent can check downstream impact before it changes anything.
* **Governance.** Every action is classified by its effect and passes a permission gate you control.
## How it fits together
Everything you do in Alkera happens in a **workspace**. A workspace holds **chats** with the agent, **notebooks**, and **files** together in one folder, and it runs on a **machine**.
```mermaid theme={null}
flowchart TB
org["Organization
members, teams, connections, knowledge, billing"]
org --> ws1["Workspace: Main"]
org --> ws2["Workspace: Q3 revenue"]
ws2 --> c1["Chats"]
ws2 --> n1["Notebooks"]
ws2 --> f1["Files"]
ws2 -. runs on .-> m["Machine
Standard or an org machine"]
```
| Concept | What it is |
| - | - |
| [Organization](/organization/teams) | Your company's account. It owns members, teams, connections, knowledge, and billing. |
| [Workspace](/workspaces/overview) | A shared place for one piece of work. Every member has a **Main** workspace and can create more. |
| [Chat](/workspaces/chats) | A session with the agent inside a workspace. Several people can join one chat at once. |
| [Notebook](/notebooks/overview) | A reactive SQL and Python notebook, edited live by people and the agent. |
| [Files](/workspaces/files) | All the files from all of your workspaces, plus files shared with you. |
| [Machine](/workspaces/machines) | The compute a workspace runs on: shared **Standard** compute, or a dedicated CPU or GPU machine. |
## Where it runs
Alkera runs in your browser at [app.alkera.ai](https://app.alkera.ai). There is nothing to install. The agent and your notebooks run on managed machines, not in your browser, so work continues when you close the tab.
You can also start chats from [Slack](/workspaces/slack) by mentioning the Alkera bot.
**IDE extensions and a CLI are coming soon.** They will work with the same workspaces and chats as the web app, and let you run workspaces locally on your own machine.
## Get started
Create an account or join your organization.
Connect a warehouse, ask the agent a question, and build a notebook.
# Dashboards
Source: https://docs.alkera.ai/notebooks/dashboards
Coming soon: share a notebook as an interactive dashboard.
**Dashboards are coming soon.** This page describes what is on the way.
A dashboard will be a view of a notebook for people who need the results, not the code. You choose which cells to hide. The Markdown, inputs, and charts you keep make up the dashboard, and it stays connected to the live notebook.
Because the notebook is [reactive](/notebooks/reactivity), changing an input on a dashboard will recalculate only the numbers and charts that depend on it.
Until dashboards arrive, share the [workspace](/workspaces/overview#sharing) with **Can view** access so teammates can open the notebook and its outputs.
Build the analysis a dashboard will come from.
# Environment and kernel
Source: https://docs.alkera.ai/notebooks/environment
The Python environment your notebooks use, the kernel that runs them, and the compute underneath.
A notebook's code runs in a **kernel** on the workspace's [machine](/workspaces/machines), using the workspace's Python **environment**.
## The default environment
Each workspace has a default environment that every notebook in it uses. It comes with:
| Area | Packages |
| - | - |
| Data | polars, pandas, pyarrow, duckdb, numpy |
| Charts | matplotlib, seaborn, plotly, altair |
| Widgets | ipywidgets, anywidget |
| Science | scipy, scikit-learn, statsmodels |
| I/O | requests, httpx, sqlalchemy, openpyxl |
| Utilities | pydantic, tqdm, beautifulsoup4 |
## Add packages
Open **Panels** in the toolbar and choose **Environment**.
Type package names in the box, such as `lightgbm` or `scikit-learn==1.5`, and click **Install**.
The package is added under **Requirements**. Alkera builds the environment and lists everything under **Installed**.
Click **Remove** next to a requirement to drop it. You can also ask the agent to install a package. It asks first, depending on your [permission mode](/foundations/agent-and-tools#permission-modes).
Packages are installed into the workspace's environment, so every notebook in the workspace gets them.
### Packages after sleep
The environment's package list, and a lock file that pins exact versions, are saved in the workspace's folder. The installed packages themselves are not. After the workspace [sleeps](/workspaces/overview#sleep-and-wake) or moves to another machine, Alkera rebuilds the environment from that list, so the first run can take longer.
Packages installed any other way, such as with `pip install` in a shell, are not on the list and are gone after sleep. Add them in the **Environment** panel so they stay.
## The kernel
A kernel starts the first time you run a cell. Opening a notebook does not start one. Everyone in the notebook shares its kernel.
* **Interrupt** stops the running cell. If it does not stop, Alkera escalates to a restart.
* **Restart** clears every variable in memory. Saved outputs stay on screen, marked **Not run in this kernel**.
* The toolbar shows memory use and warns at 80%. If the kernel runs out of memory, it is restarted.
When the workspace [sleeps](/workspaces/overview#sleep-and-wake), the kernel stops. Variables are not kept, so re-run the notebook when you return. If the workspace is asleep when you run a cell, the notebook shows **Waking the workspace…** first.
## Compute
Notebooks run on the machine their workspace runs on. For large data, long-running jobs, or training models, move the workspace to a dedicated CPU or GPU [machine](/workspaces/machines#move-a-workspace-to-another-machine).
Files and the environment's package list move with the workspace, and the environment is rebuilt on the new machine.
## Notebook settings
Open **Settings** (the gear in the toolbar) to change:
* **When a cell runs**: autorun or lazy. See [Reactivity](/notebooks/reactivity#run-modes).
* **Frames as**: Polars or pandas for SQL results.
* **Rows per SQL result**: a cap on rows returned by SQL cells.
## Related
Standard compute and dedicated CPU and GPU machines.
Run, interrupt, and restart from the keyboard.
# Outputs and charts
Source: https://docs.alkera.ai/notebooks/outputs
Tables, Alkera charts, plots from your favorite library, images, Markdown, and interactive widgets.
A cell's output is whatever its last expression returns, plus anything it displays along the way.
## What renders
| Output | Examples |
| - | - |
| **Tables** | Polars and pandas dataframes, SQL results. Page, filter, sort, and copy as CSV. |
| **Alkera charts** | `alkera.chart(...)` |
| **Other charts** | Matplotlib, seaborn, Plotly, Altair, and Vega-Lite |
| **Images** | PNG, JPEG, GIF, WebP, SVG |
| **Text** | Markdown, HTML, JSON, plain text |
| **Widgets** | `alkera.ui` widgets, ipywidgets, anywidget |
| **Errors** | A traceback, with notes on what went wrong |
Everything renders without loading anything from the internet.
## Alkera charts
`alkera.chart` is a declarative chart library. Pass it a dataframe, pick a mark, and map columns to channels.
```python theme={null}
alkera.chart(weekly).line(x="week", y="revenue", color="region").title("Weekly revenue")
```
Marks include `line`, `bar`, `area`, `point`, `histogram`, `heatmap`, `pie`, and `boxplot`. Add `.tooltip()` and `.zoom()` for interaction. `alkera.chart` also accepts Altair charts and Vega-Lite specs.
Prefer another library? Matplotlib, seaborn, Plotly, and Altair figures render natively. Return the figure as the cell's last expression.
## Layout and display
The `alkera` module has helpers for richer outputs:
* `alkera.md(...)` and `alkera.html(...)` render Markdown and HTML.
* `alkera.image(...)` shows an image.
* `alkera.hstack(...)` and `alkera.vstack(...)` arrange outputs side by side or stacked.
* `alkera.callout(...)` highlights a note or warning.
* `alkera.status.progress_bar(...)` and `alkera.status.spinner(...)` show progress while a cell runs.
## Widgets
Widgets are inputs that drive [reactivity](/notebooks/reactivity). Assign a widget to a variable in one cell, read its `.value` in another, and that cell re-runs whenever the widget changes.
```python theme={null}
region = alkera.ui.dropdown(["EMEA", "AMER", "APAC"], value="AMER", label="Region")
region
```
```python theme={null}
alkera.chart(weekly.filter(pl.col("region") == region.value)).line(x="week", y="revenue")
```
Available widgets: `slider`, `number`, `text`, `text_area`, `checkbox`, `switch`, `dropdown`, `radio`, `multiselect`, `date`, `button`, and `run_button`.
ipywidgets and anywidget work too. Wrap one in `alkera.widget(...)` to make it reactive.
Use `alkera.ui` rather than `mo.ui`. marimo's widgets are not available in Alkera notebooks.
## Work with an output
A cell's **⋯** menu has **Clear output**, **Collapse output**, **Open output in a new tab**, **Download image**, and **Copy cell link**.
Outputs are saved with the notebook, so they show when you reopen it or preview it in Files. A saved output from an earlier session is marked **Not run in this kernel** until you run the cell again.
## Related
How widgets and changes flow through the notebook.
Coming soon: share outputs as an interactive dashboard.
# Notebooks
Source: https://docs.alkera.ai/notebooks/overview
Reactive SQL and Python notebooks that you and the agent edit together.
An Alkera notebook is a reactive SQL and Python notebook that lives in a workspace. You can write cells yourself, ask the agent to build the notebook for you, or both at once. The agent edits the same notebook you have open, so you see its cells and outputs as it works.
This section covers:
* [Reactivity](/notebooks/reactivity): how cells track their dependencies and re-run.
* [SQL and Python](/notebooks/sql-and-python): querying connections and using results as dataframes.
* [Outputs and charts](/notebooks/outputs): tables, charts, and widgets.
* [Environment and kernel](/notebooks/environment): packages, the kernel, and compute.
## Create a notebook
Notebooks live in a [workspace](/workspaces/overview), and their kernel runs on the workspace's [machine](/workspaces/machines). Like any workspace file, a notebook is saved in Files and copied onto the machine while the workspace is awake. See [Where workspace files live](/workspaces/files#where-workspace-files-live).
* **Ask the agent.** In any chat, ask for a notebook: "Build a notebook that tracks weekly signups by channel." The agent creates it, adds cells, and runs them.
* **Create one yourself.** Open the workspace's files and click **New notebook**. It opens with one empty cell.
A new notebook opens in the **Notebook** view. Switch to **Source** to edit the underlying file as text.
## Cells
A notebook is a list of cells. Each cell is one of:
* **Python**: any Python code.
* **SQL**: a query against a [connection](/foundations/plugins-and-connections), or DuckDB over the notebook's own data. See [SQL and Python](/notebooks/sql-and-python).
* **Markdown**: text, headings, and notes.
To add a cell:
* Click **Add a cell** at the end of the notebook.
* Open a cell's **⋯** menu and choose **Insert cell above**, **Insert cell below**, or one of the **Insert Markdown** and **Insert SQL** items.
* Select a cell and press A to insert above or B to insert below.
Drag a cell's handle to reorder it.
Run a cell with its **Run cell** button or Cmd + Enter (Ctrl + Enter on Windows and Linux). See [Keyboard shortcuts](/notebooks/shortcuts) for the rest.
## Build it with the agent
The agent has full control of notebooks through its notebook tools. It can:
* Create notebooks, and add, edit, move, and delete cells.
* Run a cell, the whole notebook, the stale cells, or everything upstream or downstream of a cell.
* Read outputs, variables, and dataframes, and follow the dependency graph.
* Install packages and change notebook settings.
* Show any cell's output, such as a table or chart, right in the chat.
Notebook steps in the chat carry **Go to cell**, which opens the notebook at that cell. Running cells and installing packages are actions the agent asks before taking, depending on your [permission mode](/foundations/agent-and-tools#permission-modes).
## Work together
Notebooks are edited live by everyone in them, including the agent.
* Avatars in the toolbar show who is in the notebook. Each cell shows who is editing it, and the agent appears as **Alkera**.
* Typing from several people in one cell merges as they type.
* Everyone shares one kernel, so everyone sees the same outputs. Each run records who ran it, such as "by Alkera agent for Alice".
* A cell is not re-run automatically while someone is editing it.
## The file format
A notebook is a plain Python file ending in `.alknb.py`. It builds on [marimo](https://marimo.io)'s file format: each cell is a function, so the notebook is readable Python, diffs cleanly in git, and runs in marimo with the `alkera` package installed.
```python theme={null}
# >>> alkera
# format = "1.0"
# dataframe = "polars"
# <<< alkera
import marimo
app = marimo.App()
with app.setup(alkera_id="0000000001"):
import alkera
@app.cell(alkera_id="0000000002")
def _():
orders = alkera.sql(
rf"""
SELECT * FROM analytics.orders
""",
connection="Snowflake prod",
)
return (orders,)
```
Alkera adds a settings block at the top, a stable ID on each cell, and the `alkera` module for SQL, charts, Markdown, and widgets. Outputs are saved next to the notebook, not in the file.
## View and download
In [Files](/workspaces/files), a notebook previews read-only with its saved outputs. Previewing never starts a kernel. **Download** saves the `.alknb.py` file. Individual outputs can be downloaded as images or copied as CSV.
## In this section
The dependency graph, stale cells, and run modes.
SQL cells, connections, and dataframes.
Tables, charts, widgets, and more.
Packages, the kernel, and compute.
Every notebook shortcut.
Coming soon: share a notebook as an interactive dashboard.
# Reactivity
Source: https://docs.alkera.ai/notebooks/reactivity
Cells know what they read and what reads them, so results stay current as inputs and queries change.
Alkera notebooks are **reactive**. Each cell knows which names it defines and which names it reads, so the notebook forms a dependency graph. Change an input or a query, and the cells that depend on it re-run. A result on screen always matches the code above it.
There is no hidden state from running cells out of order, because the order cells run in comes from the graph, not from their position on the page.
## How the graph is built
Alkera reads each cell's code to find:
* **Definitions**: the variables, functions, and imports the cell creates.
* **References**: the names it reads that another cell defines.
A cell that reads `orders` depends on the cell that defines `orders`. SQL cells take part too. A SQL cell's result name is a definition, and a DuckDB query that selects from a dataframe is a reference to it.
In the gutter beside each cell, **↑** and **↓** counts show how many cells it reads from and how many read it. Hover to highlight them, and click to jump there.
### Rules that keep the graph sound
* Each name is defined in one cell. If two cells define the same name, both are flagged, and the cell offers to make the name local to that cell or to rename it.
* Cells can't depend on each other in a loop. Cells in a cycle are flagged and do not run.
* Names that start with an underscore are local to their cell, so `_tmp` in one cell does not clash with `_tmp` in another.
## Run modes
Choose how the notebook reacts in **Settings** (the gear in the toolbar), under **When a cell runs**.
| Mode | Setting | What happens when a cell runs |
| - | - | - |
| **Autorun** (default) | **Cells that read a changed value re-run** | Every cell downstream re-runs, in dependency order. |
| **Lazy** | **They are marked stale instead** | Downstream cells are marked **Stale**. Run them when you are ready. |
Lazy mode is useful when downstream cells do something expensive, such as a slow computation or a query against a billed warehouse.
When a run would take a long time, Alkera asks first with **Run these cells?** and an estimated time.
## Cell status
The dot in each cell's gutter shows its state.
| Status | Meaning |
| - | - |
| **Up to date** | Its output matches its code and inputs. |
| **Edited** | The code changed since it last ran. |
| **Stale** | Something it reads changed. Run it to update. |
| **Not run** | It has not run in this kernel. |
| **Queued** / **Running** | Waiting to run, or running. |
| **Error** | It raised an error. |
| **Interrupted** / **Stopped** | The run was interrupted, or the cell stopped itself. |
| **Skipped** | It did not run because a cell it depends on failed. |
| **Disabled** | It is turned off and never runs. |
## Run controls
The toolbar has **Run all**, **Run stale**, and **Interrupt**. The **Kernel** menu adds **Restart**, **Restart and run all**, **Interrupt and clear the queue**, **Shut down**, and **Clear all outputs**.
Each cell's **⋯** menu adds **Run above** and **Run below**.
## See the whole graph
Open **Panels** in the toolbar and choose **Graph** to see the notebook's dependency graph. Filter it to a cell's **Upstream** or **Downstream** to see what feeds it and what it affects.
**Variables** lists every name the notebook defines and jumps to the cell that defines it. **Outline** lists the notebook's Markdown headings.
## Widgets drive reactivity
Interactive widgets such as sliders and dropdowns are values in the graph. Move a slider and every cell that reads it re-runs. See [widgets](/notebooks/outputs#widgets).
## Related
How SQL results join the graph.
Widgets and the outputs they drive.
# Keyboard shortcuts
Source: https://docs.alkera.ai/notebooks/shortcuts
Jupyter-style shortcuts for running, editing, and moving between cells.
Notebook shortcuts follow Jupyter. Mod means Cmd on macOS and Ctrl on Windows and Linux.
A notebook has two modes. In **edit mode** you are typing in a cell. In **command mode** a cell is selected but you are not typing in it. Press Esc to go to command mode and Enter to edit the selected cell.
## Both modes
| Shortcut | Action |
| - | - |
| Mod + Enter | Run cell |
| Shift + Enter | Run cell and move to the next |
| Alt + Enter | Run cell and insert one below |
| Mod + F | Find |
| Mod + Shift + H | Find and replace |
## Command mode
| Shortcut | Action |
| - | - |
| Enter | Edit cell |
| J or ↓ | Next cell |
| K or ↑ | Previous cell |
| A | Insert cell above |
| B | Insert cell below |
| D, D | Delete cell |
| Z | Restore deleted cell |
| Shift + M | Merge with next cell |
| Mod + Shift + ↑ / ↓ | Move cell up or down |
| Y | Change to Python |
| M | Change to Markdown |
| S | Change to SQL |
| O | Collapse output |
| I, I | Interrupt |
| 0, 0 | Restart kernel |
| Mod + Z | Undo |
| Mod + Shift + Z or Mod + Y | Redo |
## Edit mode
| Shortcut | Action |
| - | - |
| Esc | Leave the editor |
| Mod + Shift + - | Split cell at cursor |
| Mod + / | Toggle comment |
# SQL and Python
Source: https://docs.alkera.ai/notebooks/sql-and-python
Query your warehouses in SQL cells and use the results as dataframes in Python.
SQL cells query a connected warehouse and return a dataframe by name. Later Python cells use it like any other variable.
## SQL cells
Add a SQL cell with **Insert SQL below** in a cell's **⋯** menu, or select a cell and press S to turn it into SQL. The cell header has two settings:
* **Connection**: where the query runs. Pick one of the workspace's [connections](/foundations/plugins-and-connections), or **DuckDB** to query the notebook's own dataframes. DuckDB is the default.
* **Result name**: the variable the result is stored in. Other cells read the result by this name. The default, `_df`, starts with an underscore, so it stays local to the cell. Rename it to use the result elsewhere.
A query against a connection runs with that connection's credentials. Hover the connection to see whose they are. If the connection is not available in the workspace, the cell says so and fails when it runs.
Turn off **Show result** in the cell's **⋯** menu to keep the result as a variable without displaying it.
### Results
Results show as a table you can page through, filter, and sort. **Copy as CSV** copies the result.
Results are dataframes. By default Alkera uses Polars when it is installed. Change it in notebook **Settings** under **Frames as**: **Polars**, **pandas**, or whichever is installed. **Rows per SQL result** caps how many rows a query returns. Leave it empty to keep every row.
## Use results in Python
A SQL cell's result is a normal Python variable.
```python theme={null}
# A SQL cell with the result name `orders` ran against Snowflake.
import polars as pl
weekly = (
orders
.group_by_dynamic("ordered_at", every="1w")
.agg(revenue=pl.col("amount").sum())
)
```
The Python cell depends on the SQL cell, so changing the query re-runs it. See [Reactivity](/notebooks/reactivity).
You can also run SQL from Python with `alkera.sql`:
```python theme={null}
orders = alkera.sql(
"SELECT * FROM analytics.orders WHERE ordered_at >= '2026-01-01'",
connection="Snowflake prod",
)
```
## Join across warehouses
A warehouse query cannot see another warehouse or the notebook's dataframes. To combine data from two sources, query each one in its own cell, then join the results in a **DuckDB** SQL cell or in Python.
```sql theme={null}
-- DuckDB cell. `orders` came from Snowflake, `accounts` from Postgres.
SELECT a.segment, SUM(o.amount) AS revenue
FROM orders o
JOIN accounts a USING (account_id)
GROUP BY a.segment
```
## Python cells
Python cells run any Python in the workspace's [environment](/notebooks/environment). Each cell's last expression is displayed as its output. Variables a cell defines are available to every cell that reads them.
## Markdown cells
Markdown cells hold headings, text, lists, and links. They render in place, and their headings appear in the **Outline** panel. To write Markdown from Python, use `alkera.md`.
## Related
How SQL and Python cells stay current.
The warehouses a SQL cell can query.
# Billing & usage
Source: https://docs.alkera.ai/organization/billing
Plans, credits, top-ups, and how usage is tracked and allocated across your organization.
Every plan runs the same Alkera agent. Plans differ in how much usage they include and what your organization can do.
## Plans
| Plan | Price | Includes |
| - | - | - |
| **Free** | \$0 | Limited usage, 10 GB of storage, and native integrations across your stack. |
| **Plus** | \$50 / month | Extra usage, 1 TB of storage, and access to all models. |
| **Pro** | \$250 / month | Significantly increased usage, 5 TB of storage, dedicated support, and early access to new features. |
| **Enterprise** | Custom | SSO, SAML, and SCIM. Audit logs, pooled usage, VPC and on-premise deployment, zero data retention, data residency controls, and SLAs. |
See [alkera.ai/pricing](https://alkera.ai/pricing) for current pricing. For Enterprise, email [sales@alkera.ai](mailto:sales@alkera.ai).
## What uses credit
Your plan comes with a monthly allowance of credit. These draw on it:
* **Model usage.** Each message to the agent uses credit based on the model, the effort, and the work involved. It is billed to the person who sends the message.
* **[Machines](/workspaces/machines).** Org machines bill by the hour while running. Standard compute is included.
The allowance resets each billing cycle.
## Manage your plan
Open the account menu at the bottom of the sidebar and choose **Manage plan**.
* **Your plan** shows your current plan. Click **Change plan** to switch.
* **This cycle's usage** shows how much of your allowance you have used and when it resets.
* **Add credits** buys a top-up of \$25, \$50, \$100, or \$250, or a custom amount from \$5. Payment goes through Stripe.
* **Billing** opens the Stripe portal for your payment method and invoices, and has **Cancel subscription**.
Upgrades take effect immediately, with a prorated charge. Downgrades and cancellations take effect at the end of the billing cycle, and you can undo them until then.
## Organization billing
Org admins can buy prepaid credit for the whole organization in **Settings** under **Billing**. Buy it for:
* The **Org pool**, shared by everyone.
* A **Team pool**, for one team.
* A **Member seat**, for one person.
Prepaid credit never expires.
## Allocations
Admins can set limits for each team and member in [Teams](/organization/teams). Each team's **Allocations** list shows its members' **Budget** in USD per cycle, their **Storage**, and what they have **Spent this cycle**.
## Usage
Open **Usage** in the sidebar to see where credit goes. Choose a metric (**Requests**, **Budget**, **Storage**, or **Machines**), a scope (**Organization**, **Team**, or **Personal**), and a time window. Admins see spend and storage broken down by member.
## When credit runs out
When an allowance or budget is used up, new requests stop and the chat says why, such as "Your cycle allowance is used up." It shows when the allowance resets.
* **Admins** see **Manage plan** to add credits or upgrade.
* **Members** are asked to contact an org admin.
* Org machines stop. Files are kept.
If a payment is refunded or disputed, the credit it bought is taken back. If that leaves a balance owed, usage is paused until it is paid. The next top-up pays it first.
## Related
Hourly compute for heavy work.
Roles, invitations, and allocations.
# Teams & members
Source: https://docs.alkera.ai/organization/teams
Organizations, teams, roles, invitations, and sign-in settings.
An **organization** is your company's account in Alkera. It owns your members, teams, [connections](/foundations/plugins-and-connections), [knowledge](/foundations/knowledge-base), [machines](/workspaces/machines), and [billing](/organization/billing).
Inside it, **teams** group people. Teams nest as deep as you need, so a team can hold sub-teams. A person can be on as many teams as you like.
When you sign up without an invitation, Alkera creates a new organization and makes you its first admin.
## Teams
Open **Teams** from the **Organization** section of the sidebar. The team tree shows every team and its sub-teams. Choose a team to see its roster, with members who joined directly and members who belong through a sub-team.
Teams decide:
* Who can use a team's [connections](/foundations/plugins-and-connections#personal-and-team-connections).
* Who you can [share](/workspaces/overview#sharing) workspaces and files with in one step.
* How credit is [allocated](/organization/billing#allocations) across the organization.
## Roles
There are two roles: **Member** and **Admin**. A role is held per team, so the same person can be an admin of one team and a member of another.
| | Member | Admin |
| - | - | - |
| Use the team's connections, chats, and knowledge | Yes | Yes |
| Invite people and revoke invitations | No | Yes |
| Manage members and sub-teams | No | Yes |
Admin rights descend. An admin of a team is an admin of every team beneath it. An admin of the top team is an **Org admin**, and is an admin everywhere.
Org admins also manage organization settings, [billing](/organization/billing), [Slack](/workspaces/slack), and sign-in. Org admins and team admins can manage [machines](/workspaces/machines).
## Invitations
An admin invites someone by email and picks the team and role they join with.
Alkera emails a sign-up link. The invitation is good for seven days.
The recipient signs up through the link, or clicks **Accept invitation** if they already have an account. They join the team and every team above it.
If you invite someone who already belongs to your organization, they are added right away with no email. An admin can revoke a pending invitation before it is used.
Invite colleagues rather than having them sign up on their own. Signing up without an invitation creates a separate organization.
## Multiple organizations
You can belong to more than one organization, such as your company's and a client's. Each organization keeps its own workspaces, files, connections, knowledge, and billing.
Switch organizations from the account menu, under your profile icon at the bottom left of the sidebar:
* **Switch organization** lists the organizations you belong to, with a check next to the one you are in. Choose another to switch to it.
* **Create organization**, at the end of that list, starts a new organization with you as its admin.
* **Pending** lists organizations that added you, for example through their directory, but that you have not joined yet. Click **Join** to join one. It then appears under **Switch organization**.
When you belong to more than one organization, the account menu shows which one you are in.
## Organization settings
Org admins open **Settings** from the account menu at the bottom of the sidebar. The **General** tab has:
* **Organization name** and **Members**.
* **Sign-in methods**: allow or turn off sign-in with Google and GitHub.
* **Slack**: connect the [Slack app](/workspaces/slack).
* **Knowledge sync**: allow sharing [knowledge](/foundations/knowledge-base#knowledge-sync) across the organization.
## Single sign-on
Organizations on the Enterprise plan can connect an identity provider in **Settings** under **Single sign-on**.
* **SSO** over OIDC or SAML, for your organization's email domains. Turn on **Require SSO** to hide password sign-in.
* **Group → role mapping** assigns roles from your identity provider's groups.
* **Automated provisioning (SCIM 2.0)** adds and removes members from your directory. Generate a token and give it to your identity provider. The token is shown once.
* **Audit log** records activity in your organization.
Single sign-on, directory sync, and the audit log are available on the Enterprise plan.
## Related
Plans, credits, and team allocations.
Personal and team connections.
# Quickstart
Source: https://docs.alkera.ai/quickstart
Connect a warehouse, ask the agent a question, and build your first notebook.
This page takes you from a new account to a working notebook. If you do not have an account yet, start with [Get access](/get-access).
## 1. Connect your data
The agent works with the data your connections reach.
Click **Connections** in the sidebar, then **Add connection**.
Under **Who this connection is for**, pick **Just me**, or a team if you are its admin.
Pick the integration, such as Snowflake or PostgreSQL, choose how to sign in, and fill in its details. Set the **Deployment tier** so the agent knows whether it is touching production.
Click **Save connection**. Alkera checks the connection before it saves, so a connection that cannot connect is never stored.
See [Plugins & Connections](/foundations/plugins-and-connections) for every supported integration.
No warehouse handy? You can still upload a CSV, Parquet, or any other flat file, such as TSV, JSON, or Excel, to the workspace and ask the agent to analyze it.
## 2. Start a chat
Click **Chat** in the sidebar. Your **Main** workspace is listed first under **Workspaces**. Click **Chat** on its row to start a chat in it.
In the composer:
* **Model** and **Effort** pick the model and how hard it reasons. Set your defaults in **Preferences**.
* **Permission mode** decides what the agent may do without asking. **Default** runs reads freely and asks before changes. See [permission modes](/foundations/agent-and-tools#permission-modes).
Ask a question about your data:
```text theme={null}
Which five customers had the largest drop in order volume last quarter?
```
The agent looks at your schemas and the [knowledge base](/foundations/knowledge-base), runs queries, and streams its answer. Each step appears as a card you can expand. Query results show as tables.
## 3. Approve what it proposes
When the agent wants to do something that changes state, such as writing a file or running a notebook cell, it stops and shows an approval card. Choose **Allow once**, **Reject once**, or **Always allow** from the dropdown.
Nothing that changes your data or files runs without passing this gate, unless you choose a mode that allows it.
## 4. Build a notebook
Ask the agent to turn the analysis into a notebook:
```text theme={null}
Turn this into a notebook with a weekly trend chart and a region filter.
```
The agent creates an `.alknb.py` notebook in the workspace, writes SQL and Python cells, runs them, and shows the outputs in the chat. Click **Go to cell** on any step to open the notebook at that cell. You can edit cells alongside the agent while it works.
You can also create one yourself: open the workspace's files and click **New notebook**. See [Notebooks](/notebooks/overview).
## 5. Bring your team in
* **Share the workspace.** Open the workspace's **⋮** menu and choose **Share…**. Add people or teams and pick their access. See [Sharing](/workspaces/overview#sharing).
* **Invite teammates.** If they are not in your organization yet, an admin can invite them from [Teams](/organization/teams#invitations).
* **Record what you know.** Add business definitions and conventions in **Knowledge** so the agent uses them in every chat.
## Learn more
Main and project workspaces, sharing, and sleep.
The composer, models, approvals, and working together.
Reactive SQL and Python notebooks built with the agent.
Effects, permission modes, and approvals.
# Chats
Source: https://docs.alkera.ai/workspaces/chats
Sessions with the agent inside a workspace: the composer, models, approvals, and working together live.
A **chat** is a session with the agent inside a [workspace](/workspaces/overview). The agent can query your data, write and run code, edit files, and build notebooks. It runs on the workspace's [machine](/workspaces/machines), not in your browser, so it keeps working when you close the tab.
## Start a chat
* Click **Chat** on a workspace's row in the sidebar, or **New chat** on the workspace page.
* Click **New from template** to start from a chat someone saved as a template.
The chat is created when you send the first message.
## The composer
Type your request in the composer and press **Send**. Below the text box:
| Control | What it does |
| - | - |
| **Attach files** | Adds files or images to your message. You can also paste or drop them in. |
| **Model** | The model the agent uses. Alkera offers Anthropic and OpenAI models. You can switch models in an open chat. |
| **Effort** | How hard the model reasons, from **Low** up to **Max**, depending on the model. Higher effort is slower and uses more credit. |
| **Permission mode** | What the agent may do without asking. Press Shift + Tab to cycle modes. See [permission modes](/foundations/agent-and-tools#permission-modes). |
Set your default model and effort for new chats in **Preferences**, from the account menu at the bottom of the sidebar.
While the agent is working, **Send** becomes **Stop**. A message you send mid-turn is queued and runs when the current turn ends.
Slash commands are not available in the web app. Ask for what you want in plain language instead.
## What the agent shows you
The agent streams its answer. Each step it takes appears as a card you can expand:
* **Queries** show a result table.
* **File edits** show what was added, updated, renamed, or deleted. Click **Show diff** to see the change.
* **Shell commands** show their output.
* **Notebook steps** show the cells it created, edited, or ran, with **Go to cell** to open the notebook there. Tables, charts, and images from a notebook can appear right in the chat.
Large results are stored rather than pasted into the conversation. See [large results](/foundations/agent-and-tools#large-results).
## Approvals and questions
When the agent reaches an action your permission mode does not allow on its own, it stops and shows an **approval card** describing what it wants to do and why it needs approval.
* **Allow once** (Enter) runs it this time.
* **Reject once** (Esc) refuses it this time. The agent adapts and continues.
* **Always allow**, from the dropdown, saves a rule so the same action passes next time. Only the chat's owner can choose it.
When the agent needs a decision from you, it asks with a **question card**. Pick an answer, or choose **Other…** to type your own.
A chat waiting on you shows **Needs your answer** in the sidebar.
## Work together
Several people can be in one chat at once.
* Avatars at the top show who else is in the chat.
* The composer draft is shared. Everyone with edit access can type in it together and see each other's cursors.
* People with **Can view** access can read the chat but not send messages.
To give someone access, [share the workspace](/workspaces/overview#sharing).
## Manage a chat
The chat header has **Rename**, **Share**, **Copy chat**, and **Delete chat**.
* **Copy chat** makes your own copy, named "(copy)".
* **Delete chat** moves the chat and its files to the [trash](/workspaces/files#trash).
* **Save as template…**, from the chat's menu in the sidebar, lets people start new chats from it with **New from template**.
## Related
Effects, permission modes, and what the agent can do.
Start chats by mentioning the Alkera bot.
# Files
Source: https://docs.alkera.ai/workspaces/files
All the files from all of your workspaces, plus files shared with you.
**Files** holds all the files from all of your workspaces, plus files shared with you.
Open it from **Files** in the sidebar.
## Places
The left rail has:
| Place | What it shows |
| - | - |
| **Home** | Your own files and folders, including your workspaces. |
| **Recent** | What you opened or changed lately. |
| **Shared with me** | Files, folders, and workspaces others shared with you. |
| **My leases** | Folders a machine is working in for you right now. See [Where workspace files live](#where-workspace-files-live). |
| **Trash** | Deleted items, kept for 30 days. |
## Work with files
Right-click any item for its actions, or use the toolbar.
* **Create**: **New folder**, **New notebook**. Notebooks can be created only inside a workspace.
* **Upload**: **Upload files** or **Upload folder**, or drag them in. A single file can be up to 1 TB.
* **Organize**: **Rename**, **Move to…**, **Copy to…**, **Duplicate**, and cut, copy, and paste.
* **Get it out**: **Download**, **Copy link**.
* **History**: **Versions** and **Details**.
Uploading over an existing file asks first. **Replace** keeps the file and adds your upload as a new version. Alkera keeps at least the newest five versions of a file, and every version from the last 90 days.
## Previews
Click a file to preview it without downloading.
| Kind | Formats |
| - | - |
| Tables | CSV, TSV |
| Documents | PDF, Markdown, HTML, plain text and logs |
| Code and config | Most languages, plus JSON, YAML, TOML, and similar |
| Images | PNG, JPEG, GIF, WebP, AVIF, SVG, and others |
| Media | MP3, WAV, M4A, AAC, OGG, FLAC, MP4, WebM, MOV |
| Notebooks | Alkera notebooks (`.alknb.py`), read-only, with their saved outputs |
Office documents and other formats show a file card that you can download.
## Where workspace files live
A workspace's files have one home: its folder in Files. The [machine](/workspaces/machines) only holds a working copy, and only while the workspace is awake.
```mermaid theme={null}
flowchart LR
asleep["Asleep
Only in Files
Nothing on machine"]
awake["Awake
Copy on machine
Synced with Files"]
asleep -- "Wake
Copy to machine" --> awake
awake -- "Sleep
Save, then clear" --> asleep
```
**While the workspace is asleep**, its files are only in Files. You can browse, preview, upload, and share them as usual. Nothing is on any machine.
**When it wakes**, Alkera copies the folder from Files onto the machine. On the machine, it is the agent's working directory, `/home/alkera`.
**While it is awake**, the working copy and Files stay in sync:
* Files the agent or a notebook writes on the machine appear in Files within moments.
* Files you upload or edit in Files reach the machine.
* If a file changes in both places at once, Alkera keeps both, saving one as a conflicted copy next to it.
* Files larger than 32 MiB that are written on the machine are not copied live. They reach Files when the workspace sleeps or moves.
While a machine is working in a folder, it holds a **lease** on it, and the folder shows who is working in it.
**When it sleeps**, Alkera saves the whole folder to Files, releases the lease, and clears the folder from the machine. Files then holds the latest copy. See [Sleep and wake](/workspaces/overview#sleep-and-wake) for when that happens.
**When it moves** to another machine, the same thing happens: the folder is saved to Files, then copied onto the new machine.
Some things never leave the machine: caches and build folders, such as `.venv`, `node_modules`, and `__pycache__`, and files matched by a `.gitignore`. They are gone after the workspace sleeps or moves.
## Sharing
Right-click a file or folder and choose **Share…**. Add people, teams, or everyone in the organization, and pick their access:
* **Can view**: open, preview, download, and copy.
* **Can edit**: also change, rename, and upload.
* **Full access**: also share and delete.
Access granted on a folder carries to everything inside it and shows as **Inherited**. Sharing a workspace's folder shares the workspace. See [Workspaces](/workspaces/overview#sharing).
## Trash
**Move to trash** removes an item from its folder. Deleting a workspace or a chat moves its files to the trash too.
Open **Trash** to **Restore** an item to where it was, or **Delete forever**. Items are deleted for good after 30 days. **Empty trash** deletes everything in it right away.
## Storage
Storage counts toward your organization's [plan](/organization/billing). Identical files are stored once across your organization, but each copy still counts toward your usage. Admins can set storage limits per team and per member.
## Related
The folder behind every workspace.
Notebooks are files in a workspace's folder.
# Machines
Source: https://docs.alkera.ai/workspaces/machines
The compute your workspaces run on: shared Standard compute, or dedicated CPU and GPU machines for your organization.
Every [workspace](/workspaces/overview) runs on a **machine**. The agent's commands, your notebook kernels, and the workspace's live folder all run there.
Which machine a workspace runs on is a setting of the workspace. You can change it at any time, and the workspace's files come with it.
## Standard and org machines
| | Standard | Org machines |
| - | - | - |
| What it is | Alkera's shared compute. Each workspace runs in its own isolated sandbox. | Dedicated CPU or GPU machines your organization buys. |
| Setup | None. Workspaces run here by default. | An admin buys one from **Machines**. |
| Cost | Included. | Compute billed per hour while running. Storage billed per GB, running or stopped. Both draw on your organization's credits. |
| Good for | Most chats and notebooks. | Large data, long jobs, and training models on a GPU. |
Whether you can buy machines, and how many, depends on your [plan](/organization/billing). If your plan does not include them, the **Machines** page says so.
## Buy a machine
Organization admins and team admins can open **Machines** from the **Organization** section of the sidebar.
Click **Buy machine**, then pick an offering. Each one lists its CPU or GPU, memory, hourly rate, storage price, and whether it is in stock.
Set:
* **Name**.
* **Storage (GB)** for its disk.
* **Use**: **Assigned** to specific people, or **Org pool** to serve anyone's chats. Org pool requires the Enterprise plan.
* **Owned by**: the team that owns it.
* **Who can use it**: teams or members, or **Add everyone**. See [Share machines with care](#share-machines-with-care).
* **Stop when idle**: **Never**, or after 15, 30, or 60 minutes, or 4 hours.
* **Monthly cap**: the most it may spend in a month. Leave it empty for no cap.
The dialog shows the hourly rate and the storage price drawn from your credits. Click **Buy and start**.
Organization admins can also choose a **Default for new workspaces**.
## Storage
An org machine has two disks:
* **Storage**, the size you choose with **Storage (GB)**. This is the machine's persistent disk. It holds the folders of the chats that are awake, their Python environments, and package caches. It survives a stop.
* A **system disk** for the operating system and temporary scratch. It is reset every time the machine stops.
The storage disk is a working area, not where your files live. Your files live in [Files](/workspaces/files). While a chat is awake, its folder is copied onto the machine. When the chat [sleeps](/workspaces/overview#sleep-and-wake), Alkera saves the folder back to Files and clears it from the machine. See [Where workspace files live](/workspaces/files#where-workspace-files-live).
### How much storage you need
Only awake workspaces take up space on the storage disk. Size the disk for the busiest moment: the most storage that the workspaces awake **at the same time** will use together, including their files, Python environments, and caches.
For example, if three people usually work at once in workspaces that use about 20 GB each, choose at least 60 GB, plus headroom for large intermediate files. Workspaces that are asleep take no space, so the total size of every workspace on the machine does not matter.
| | Survives a chat going to sleep | Survives a machine stop | Survives deleting the machine |
| - | - | - | - |
| Files in workspace folders | Yes, saved to Files | Yes, saved to Files | Yes, saved to Files |
| Notebook environment package lists | Yes | Yes | Yes |
| Packages installed from the shell, caches | No | No | No |
| Anything in memory, running processes | No | No | No |
| Everything else on the storage disk | Yes | Yes | No |
### Storage pricing
Storage is billed per GB per month, by the minute, whether the machine is **running or stopped**. Only deleting the machine stops storage charges. The machine's storage does not count toward your plan's [file storage](/workspaces/files#storage). Files count toward your plan once they are saved to Files.
### Grow the disk
Choose **Grow disk** to make the storage disk larger. Disks only grow. To get a smaller disk, buy a new machine and [move your workspaces](#move-a-workspace-to-another-machine) to it. Some machines restart to grow their disk, and running chats finish first.
A machine shows **Almost out of disk** when its storage is 95% full. Grow the disk, or free up space, before chats start failing to write.
### On Standard
On **Standard**, each workspace gets a share of a shared machine's disk while it is awake. Nothing is kept on the machine between sleeps except what is saved to Files, so a woken chat starts with a fresh environment. Standard storage is not billed separately.
## Share machines with care
**Workspaces on a machine you buy are not isolated from each other.** Unlike **Standard**, where each workspace runs in its own sandbox, an org machine gives workspaces direct access to its hardware. Anyone whose workspace runs on the machine, and the agent working for them, can read files and processes from other workspaces on it.
Only let people use a machine if you would be comfortable with them seeing each other's work on it. Use separate machines for teams or data that must stay apart.
## Start and stop
An org machine runs only when it needs to.
* **Starting is automatic.** Sending a message, or opening a chat or workspace that runs on a stopped machine, starts it. This takes a minute or two, and the chat shows that the machine is starting. Your message is sent as soon as it is ready.
* **Stop when idle** stops the machine once nothing on it has worked for the time you chose. Chats on it go to sleep first, so their files are saved.
* **Stop** stops it by hand. Running chats get up to two minutes to finish. A chat interrupted by a stop says so, and continues when you send a message.
A machine also stops when it reaches its **Monthly cap**, or when your organization runs out of credit. Its storage is still billed while it is stopped. If your organization stays out of credit for 14 days, the machine is deleted. Alkera sends notices before that happens.
## Manage a machine
Each machine has **Start**, **Stop**, **Rename**, **Settings**, **Who can use it**, **Grow disk**, and **Delete**. Its page shows usage this month, the workspaces on it, and a timeline of what happened.
| State | Meaning |
| - | - |
| **Starting** | Booting. |
| **Running** | Ready. Compute and storage are billing. |
| **Almost out of disk** | Its storage is 95% full. Grow its disk or free up space. |
| **Not responding** | Alkera cannot reach it. |
| **Stopping** / **Stopped** | Not running. Only storage is billing. |
| **Waiting for hardware** | The provider has no capacity right now. |
| **Couldn't start** | Starting failed. |
**Deleting a machine destroys its storage disk.** Files in your workspaces are kept, because they are saved to [Files](/workspaces/files). Anything else on the disk is lost.
## Move a workspace to another machine
You need **Full access** to the workspace.
On the workspace, click its machine chip and choose **Change workspace machine**.
Choose **Standard** or a machine you can use. Check **Stop running chats now** to move without waiting for the agent to finish.
Click **Move workspace**. Running chats stop and continue on the new machine.
Files move with the workspace. Installed packages, running processes, and anything outside the workspace folder do not.
## Related
Sleep, wake, and what happens when a machine is deleted.
How machine time draws on your credits.
# Workspaces
Source: https://docs.alkera.ai/workspaces/overview
A shared place for one piece of work: its chats, notebooks, and files live together and run on the same machine.
A **workspace** is where a piece of work lives. Its [chats](/workspaces/chats), [notebooks](/notebooks/overview), and [files](/workspaces/files) sit together in one folder, and everything in it runs on the same [machine](/workspaces/machines). A notebook the agent writes in one chat is right there for the next chat, and for anyone you share the workspace with.
```mermaid theme={null}
flowchart LR
ws["Workspace"] --> chats["Chats"]
ws --> folder["Folder: notebooks and files"]
ws -. runs on .-> machine["Machine"]
```
## Main and project workspaces
There are two kinds of workspace.
* **Main.** Every member has one. It is private to you until you share it, and it cannot be renamed or deleted. Chats you start from [Slack](/workspaces/slack) land here.
* **Project workspaces.** Create one for each piece of work you want to keep together, such as an analysis, a pipeline fix, or a recurring report.
### Create a workspace
Click **Chat** in the sidebar, then **New workspace** at the top of the workspace list.
Enter a **Name**.
If your organization has machines you can use, pick one under **Run on**. Otherwise it runs on **Standard**, Alkera's shared compute. You can [move it](/workspaces/machines#move-a-workspace-to-another-machine) later.
Click **Create**.
## The workspace list
The sidebar on the **Chat** page lists your workspaces, with **Main** first, then your chats, then everything **Shared with me**.
Each workspace row shows:
* An unread count.
* A status dot whenever the workspace is doing something, such as starting, working, or waiting on you.
* A **Chat** button to start a new chat in that workspace.
* A **⋮** menu with **Open**, **Mark all as read**, **Rename**, **Share…**, and **Delete**.
Expand a workspace to see its chats. A chat that needs you shows **Needs your answer**.
## The workspace page
Open a workspace to see its page. It shows:
* The workspace's status and the machine it runs on.
* **Here now**: who is in the workspace, which chat each person is in, and which chats have the agent working.
* Its chats, with **New chat**.
* **Open Files**, which opens the workspace's folder.
Opening the page wakes the workspace.
## Sleep and wake
Chats and workspaces sleep when nobody is using them, so they do not hold a machine's memory while idle. They wake on their own when someone comes back. You never start or stop them yourself.
Each chat sleeps and wakes on its own. A workspace is awake while any of its chats is awake or someone has it open, and goes to sleep once all of them sleep.
### When a chat sleeps
A chat goes to sleep after **24 hours** with no activity. Activity is anything that touches the chat: a message, an answer to a question, someone opening it or being in it, the agent producing output, or an edit to the chat's files.
These keep a chat awake, however long they take:
* The agent is working on a turn.
* A message is queued behind the current turn.
* The agent asked a question and is waiting for your answer.
* A background job or another process is still running on the machine.
If a machine runs short of memory, the chat that has gone longest without use goes to sleep early. A chat that is working, or waiting on you, is never put to sleep early.
### What sleep keeps and what it clears
When a chat sleeps, Alkera saves every file in its folder to [Files](/workspaces/files), including large files, then clears the folder from the machine. See [Where workspace files live](/workspaces/files#where-workspace-files-live).
| Kept | Cleared |
| - | - |
| The chat's history | Anything in memory, including notebook variables |
| Every file in the folder, saved to Files | Running processes and background jobs |
| Notebooks, with their saved outputs | Packages installed from the shell, such as with `pip install` |
| The [notebook environment](/notebooks/environment#packages-after-sleep)'s package list | Caches and build folders, such as `.venv`, `node_modules`, `.cache`, and `__pycache__` |
| | Files matched by a `.gitignore` |
When you come back, re-run your notebook to restore its variables. Ask the agent to reinstall anything it installed from the shell, or add those packages to the notebook environment so they come back on their own.
### What wakes a chat
* Opening the chat, if you can edit it.
* Sending a message or answering a question, including from [Slack](/workspaces/slack).
* Opening the workspace, which wakes its most recently active chat.
* Opening a notebook or running a cell.
Waking copies the chat's folder from Files back onto the machine. It usually takes a few seconds. If the workspace runs on an org [machine](/workspaces/machines) that is stopped, waking starts the machine first, which takes a minute or two. A message you send while the chat wakes is sent as soon as it is ready.
### Status
| Status | Meaning |
| - | - |
| **Asleep** | Idle. A message wakes it. |
| **Waking** | Starting on its machine. |
| **Queued** | Waiting for room on its machine. |
| **Awake** | Running and ready. |
| **Working** | The agent is working in one of its chats. |
| **Moving** | Moving to another machine. |
| **Can't run** | Nothing is able to run it right now, for example because the organization is out of credit. |
If a chat's turn is interrupted, for example because its machine was stopped, the chat says **Stopped** and why. Send a message to continue.
### When its machine is gone
A workspace remembers its machine. If that machine is deleted, the workspace falls back to **Standard**.
## Sharing
Share a workspace to work on it together. Sharing a workspace shares all of its chats, notebooks, and files.
Open the workspace's **⋮** menu and choose **Share…**. Under **Add people and teams**, enter a name, an email, or a team, pick their access, and click **Share**. **Copy link** copies a link to the workspace.
| Access | What it allows |
| - | - |
| **Can view** | Read chats, notebooks, and files. Copy and export them. |
| **Can edit** | Also send messages to the agent, edit notebooks and files, and rename. |
| **Full access** | Also share with others, delete chats, move the workspace to another machine, and delete it. |
| **Owner** | Everything. Ownership moves only by transfer. |
The same access levels apply to [files and folders](/workspaces/files#sharing).
**Sharing a workspace lends your data connections.** People you share a workspace with who have edit access can query data through your [connections](/foundations/plugins-and-connections) from its chats.
Inside a workspace, you share the workspace rather than a single chat. Model usage is billed to whoever sends each message.
## Delete a workspace
Open the workspace's **⋮** menu and choose **Delete**. Its chats and files move to the [trash](/workspaces/files#trash), where you can restore them for 30 days. The owner and people with **Full access** can delete a workspace.
## Related
Working with the agent inside a workspace.
Standard compute, org machines, and moving a workspace.
# Slack
Source: https://docs.alkera.ai/workspaces/slack
Start chats with the agent by mentioning the Alkera bot in Slack.
Connect Alkera to Slack to work with the agent where your team already talks. Mention the bot in a channel, and the agent answers in a thread with result tables, charts, and files.
## Connect Slack
An org admin connects Slack once for the organization.
Open **Settings** from the account menu, and find **Slack** on the **General** tab.
Click **Add to Slack** and approve the app in your Slack workspace.
In Slack, invite the Alkera bot to the channels where you want to use it.
The Slack section then shows the bot's handle and how many people have linked their accounts, with **Reinstall** and **Disconnect**.
## Link your account
The first time you mention the bot, it sends you a direct message with **Link your Alkera account**. Open it in a browser where you are signed in to Alkera. The link expires after 15 minutes.
Linking connects your Slack identity to your Alkera account, so the agent works with your connections, knowledge, and permissions.
## Use it
* **Mention the bot** in a channel to start a chat. The agent replies in a thread.
* **Reply in the thread** to continue the chat.
* **Message the bot directly** for a private chat.
Answers include result tables, charts, and attachments such as CSV files and images. Each Slack chat also appears in your [Main workspace](/workspaces/overview#main-and-project-workspaces), where you can continue it in the browser.
When the agent needs approval, it posts a card with buttons in the thread. Only the person who started the thread can answer it.
Teammates can reply in the thread if they have edit access to the chat's [workspace](/workspaces/overview#sharing). Anyone else is asked to have the owner share the workspace with them first.
A Slack chat never starts in **Auto** or **Bypass**. If that is your saved default, it starts in **Default** instead, because other people can see and join the thread.
### Change the permission mode
Use the `/alkera` command in Slack:
```text theme={null}
/alkera mode plan
```
Modes are `ask` (the **Default** mode), `plan`, `auto`, `read-only`, and `bypass`. Only the person who started the chat can change its mode. See [permission modes](/foundations/agent-and-tools#permission-modes).
## Related
Working with the agent in the browser.
What the agent may do in each mode.