A self-hosted, container-first workspace with an AI agent at its core.
Canvas Notebook is a personal workspace that lives in a container. Think of it as a notebook that can read, write, search, and create files — with an AI you can actually talk to. You bring your files, the agent does the work.
- 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
- 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
- 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.
View Excel and CSV files directly, no downloads needed.
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 bootstrap admin is created or synchronized from env vars on every start
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:
- Install Docker (and optionally Caddy for automatic HTTPS)
- Pull the latest pre-built image from
ghcr.io— no build step, no Node.js needed - Auto-generate secrets
- Ask you to set your email, password, and public URL
- Start the container
- Install the host-side
canvas-notebookmanagement command - Configure Caddy with a Let's Encrypt TLS certificate automatically
Firewall: open ports 80 and 443 at your provider. Port 3456 stays internal behind Caddy.
DNS: point an A record for your domain to your server IP before the first request — Caddy handles the certificate automatically.
After installation, manage the VM from any directory with:
canvas-notebook help
canvas-notebook update
canvas-notebook logs
canvas-notebook status
canvas-notebook restartThe CLI runs on the VM host and remembers the install directory and Compose file for you. You do not need to cd into the project folder or run Docker Compose commands manually.
All prompts can be bypassed with environment variables — useful when provisioning a new instance automatically:
INSTALL_MODE=1 \
SETUP_CADDY=true \
BASE_URL=https://canvas.example.com \
ADMIN_EMAIL=me@example.com \
ADMIN_PASSWORD=yourpassword \
bash <(curl -fsSL https://raw.githubusercontent.com/canvascoding/canvas-notebook/main/install.sh)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 setup| 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 |
BOOTSTRAP_ADMIN_EMAIL |
Yes | Login email — created or updated on every start |
BOOTSTRAP_ADMIN_PASSWORD |
Yes | Login password |
BOOTSTRAP_ADMIN_NAME |
No | Display name for the admin (default: Administrator) |
ONBOARDING |
No | Provider setup wizard is enabled by default; set to false to skip it |
LOG_LEVEL |
No | off | error | warn | info | debug (default: info) |
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 healthRun 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.
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