https://github.com/canvascoding/canvas-notebook
Canvas Notebook — Your AI workspace with file management, agent support, and bring-your-own-model flexibility.
https://github.com/canvascoding/canvas-notebook
ai-assisstant ai-workspace file-browser marketing-tools mcp-tools media-generation multi-agent notebook notes pi-ai productivity self-hosted skills
Last synced: 12 days ago
JSON representation
Canvas Notebook — Your AI workspace with file management, agent support, and bring-your-own-model flexibility.
- Host: GitHub
- URL: https://github.com/canvascoding/canvas-notebook
- Owner: canvascoding
- License: other
- Created: 2026-01-12T19:41:25.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-27T08:42:08.000Z (17 days ago)
- Last Synced: 2026-05-27T10:17:27.536Z (17 days ago)
- Topics: ai-assisstant, ai-workspace, file-browser, marketing-tools, mcp-tools, media-generation, multi-agent, notebook, notes, pi-ai, productivity, self-hosted, skills
- Language: TypeScript
- Homepage: https://notebook.canvas.holdings
- Size: 28.9 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 📓 Canvas Notebook — Self-Hosted AI Workspace
A self-hosted, container-first workspace with an AI agent at its core.
---
## What is Canvas Notebook?
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.
---
## Features
### File Browser & Editor
- 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
### Viewers
- PDF documents, images, audio and video files — all viewable directly in the browser
### AI Agent
- 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.md` file 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
### Supported AI Providers
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
### Terminal
Full shell access in the browser — run commands, manage files, execute scripts.
### Spreadsheet Viewer
View Excel and CSV files directly, no downloads needed.
### Language Support
The interface is fully translated — switch languages from the header or the onboarding wizard. Currently supported:
- **English**
- **German** (Deutsch)
### Authentication
- 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
---
## Install
### Linux / VPS (recommended)
One command on a fresh Ubuntu or Debian server:
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/canvascoding/canvas-notebook/main/install.sh)
```
The installer will:
1. Install **Docker** (and optionally **Caddy** for automatic HTTPS)
2. Pull the latest pre-built image from `ghcr.io` — no build step, no Node.js needed
3. Auto-generate secrets
4. Ask you to set your email, password, and public URL
5. Start the container
6. Install the host-side `canvas-notebook` management command
7. 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:
```bash
canvas-notebook help
canvas-notebook update
canvas-notebook logs
canvas-notebook status
canvas-notebook restart
```
The 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.
#### Non-interactive / launch script
All prompts can be bypassed with environment variables — useful when provisioning a new instance automatically:
```bash
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)
```
---
### Mac / Windows (local)
Requires [Docker Desktop](https://www.docker.com/products/docker-desktop/) and Node.js (v18+).
```bash
npm run setup
```
The script checks Docker, creates a config file from the template, builds the image, and opens the app at `http://localhost:3456`.
---
### Hosting platforms (EasyPanel, Coolify, Portainer, etc.)
Use `ghcr.io/canvascoding/canvas-notebook:latest` as the image. Mount `/data` as a persistent volume. Set the environment variables listed in the [Configuration](#configuration) section below.
---
## Your Data
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 |
---
## Update
On Linux / VPS installs, update from anywhere on the VM:
```bash
canvas-notebook update
```
This 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:
```bash
git pull
npm run setup
```
---
## Configuration
| 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.
---
## VM Management CLI
The Linux installer creates a host-side `/usr/local/bin/canvas-notebook` command. It can be run from any directory:
```bash
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
```
Run 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
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
```
```yaml
---
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.
---
## Development
To build and run from source:
```bash
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:all
```
Pre-built images are published automatically to `ghcr.io/canvascoding/canvas-notebook` when a new release tag is pushed.
---
## License
Sustainable Use License © [Frank Alexander Weber](https://github.com/canvascoding)