A self-hosted, container-first workspace with an AI agent at its core.
Canvas Notebook is a self-hosted workspace for people who want an AI agent close to their real files, tools, and workflows. It combines a file browser, editor, terminal, chat, automations, to-dos, email, and creative AI tools in one container-first app.
Bring your workspace. Connect your preferred AI provider. Let the agent read, write, search, create, and automate without sending your whole operating system to a SaaS product.
| You need | Canvas Notebook gives you |
|---|---|
| A private AI workspace | Run it on your own VPS, homelab, or internal server |
| Agent work with real files | The agent can use your mounted /data/workspace directly |
| Provider choice | Use OpenRouter, Anthropic, Google Gemini, Ollama, Groq, Mistral, or OpenAI |
| Repeatable workflows | Turn recurring prompts into scheduled automations |
| Extensibility | Add custom skills with plain folders and SKILL.md files |
| Operational control | Update, restart, inspect logs, and reset admin access from the VM CLI |
- Creators and agencies managing campaign assets, briefs, documents, image generations, and client work
- Developers and operators who want a browser-based workspace with terminal access and reproducible self-hosting
- Teams with sensitive files that need login protection, local storage, and explicit control over public sharing
- Power users who want AI chat, file operations, automations, email, and to-dos in one place
- Notebook — files, chat, and editor in one focused workspace
- Files — browse, preview, upload, download, share, rename, move, and delete workspace files
- To-dos — track human tasks, approvals, and follow-ups that come out of agent work
- Email — connect inboxes, review messages, draft replies, and manage send policies
- Studio — manage products, personas, styles, presets, and AI-generated creative assets
- Automations — schedule recurring agent jobs for the workspace
- Security — review public file links and sharing exposure
- Usage Analytics — inspect token and cost usage across sessions, models, and users
- Browse, create, rename, move, and delete files and folders
- Upload and download files between your machine and the workspace
- Markdown editor with live preview
- Code editor with syntax highlighting for all common languages
- Document, spreadsheet, presentation, Excalidraw, HTML, and media previews
- Auto-save
- PDF documents, images, audio and video files — all viewable directly in the browser
- Chat with an AI that has direct access to your workspace
- The agent can read and write files, run shell commands, search your notes, and execute tasks autonomously
- Conversations are persisted — pick up where you left off
- Agent settings, tools, managed prompt files, model selection, and runtime status live in the app
- Skills — drop a folder with a
SKILL.mdfile into/data/skills/and the agent gains new capabilities. Skills can do things like generate images, process documents, run custom workflows, or anything else you define - Workflow automation — tell the agent to run something on a schedule (once, daily, weekly, or at a custom interval) and it will
Connect with any of the following — API keys are configured at runtime inside the app, not required at startup:
- OpenRouter (access many models through one API)
- Anthropic (Claude)
- Google Gemini
- Ollama (run models locally, inside or alongside the container)
- Groq, Mistral, OpenAI
Full shell access in the browser — run commands, manage files, execute scripts.
The interface is fully translated — switch languages from the header or the onboarding wizard. Currently supported:
- English
- German (Deutsch)
- Login-protected by default
- No public signup or in-app user management
- The first admin can be created in the setup UI after first launch
- Admin access can also be created or reset from the VM host with the management CLI
One command on a fresh Ubuntu or Debian server:
bash <(curl -fsSL https://raw.githubusercontent.com/canvascoding/canvas-notebook/main/install.sh)The installer will:
- Ask whether to use the recommended pre-built image or install from source
- Install Docker if it is missing
- Auto-generate secrets and write the local config
- Ask for the public URL/domain
- Pull the latest pre-built image from
ghcr.ioand start the container - Install the host-side
canvas-notebookmanagement command and systemd service - Optionally install and configure Caddy for automatic HTTPS, only if you choose it
By default, Caddy is not installed. If you skip it, Canvas Notebook runs on port 3456 and you can put it behind your own reverse proxy or access it directly according to your server setup.
If you enable Caddy, open ports 80 and 443 at your provider and point an A record for your domain to your server IP before the first request. Caddy then handles the Let's Encrypt certificate automatically and keeps port 3456 internal.
After installation, manage the VM from any directory with:
canvas-notebook help
canvas-notebook update
canvas-notebook logs
canvas-notebook status
canvas-notebook restart
canvas-notebook admin reset-password --email admin@example.comThe CLI runs on the VM host, not inside the app container. It remembers the install directory and Compose file, so you do not need to cd into the project folder or run Docker Compose commands manually.
Requires Docker Desktop and Node.js (v18+).
npm run setupThe script checks Docker, creates a config file from the template, builds the image, and opens the app at http://localhost:3456.
Use ghcr.io/canvascoding/canvas-notebook:latest as the image. Mount /data as a persistent volume. Set the environment variables listed in the Configuration section below.
All data is stored in a ./data directory on the host, mounted into the container at /data. It is never lost when the container is updated, restarted, or rebuilt.
| Path | What lives here |
|---|---|
/data/workspace |
Your files |
/data/sqlite.db |
Database (sessions, users, chat history) |
/data/skills/ |
Custom agent skills |
/data/secrets/ |
Integration tokens and secrets |
On Linux / VPS installs, update from anywhere on the VM:
canvas-notebook updateThis pulls the latest image, recreates the container, streams startup logs, and waits until the app is healthy. Your data is untouched because it lives in the host ./data directory.
For local / from-source installs:
git pull
npm run setupThe Linux installer generates the secrets and writes the required values for you. If you run the container manually, provide at least:
| Variable | Required | Description |
|---|---|---|
BETTER_AUTH_SECRET |
Yes | Random 32-byte base64 secret — auto-generated by the installer |
CANVAS_INTERNAL_API_KEY |
Yes | Internal API secret — auto-generated by the installer |
BETTER_AUTH_BASE_URL |
Yes | Public URL of the app, e.g. https://canvas.example.com |
Create the first admin in the setup UI, or use canvas-notebook admin reset-password --email ... --password-stdin on the VM host.
AI provider API keys (Claude, OpenRouter, Gemini, etc.) are configured inside the running app — you don't need them here.
The Linux installer creates a host-side /usr/local/bin/canvas-notebook command. It can be run from any directory:
canvas-notebook help
canvas-notebook install
canvas-notebook update
canvas-notebook logs
canvas-notebook status
canvas-notebook restart
canvas-notebook stop
canvas-notebook start
canvas-notebook health
canvas-notebook admin reset-password --email admin@example.comRun these commands on the VM/server, not inside the app container. The CLI stores the install directory and Compose file path during setup, so it can manage the container without you being in the right folder.
admin reset-password resets or creates the admin login in the running container without writing the password to config.json, .env, or Compose files. For automation, pass the password over stdin with --password-stdin.
Skills extend what the AI agent can do. A skill is a folder with a SKILL.md file:
/data/skills/
my-skill/
SKILL.md # name, description, and instructions for the agent
bin/my-skill # optional: executable makes this skill a callable tool
---
name: my-skill
description: "What this skill does and when to use it"
---
Instructions for the agent...Skills without an executable are loaded as context into the agent's system prompt. Skills with a bin/ executable become callable tools the agent can invoke directly.
To build and run from source:
git clone https://github.com/canvascoding/canvas-notebook.git
cd canvas-notebook
npm run setup # builds image and starts container
npm run dev # local dev server (no Docker)
npm run lint
npm run test:allPre-built images are published automatically to ghcr.io/canvascoding/canvas-notebook when a new release tag is pushed.
Sustainable Use License © Frank Alexander Weber