Move your vals off Val Town

Create the VM#

On your computer:

ssh exe.dev new --name=my-vals
ssh my-vals.exe.xyz

Install Deno and the kit#

On the VM:

curl -fsSL https://deno.land/install.sh | sh -s -- -y v2.9.8
export PATH="$HOME/.deno/bin:$PATH"
mkdir -p ~/vals-kit ~/vals && cd ~/vals-kit
for f in export-vals.ts export-data.ts pull-data.ts pull-env.ts prepare.ts \
    imports.json run.ts front.ts mail-router.ts sqlite.ts sqlite-global.ts \
    blob-store.ts blob.ts blob-global.ts email.ts openai.ts; do
  curl -fsSLO https://exe-staging.dev/deploy/migrate-val-town/$f
done

Install the four systemd units every val shares:

sudo tee /etc/systemd/system/val-http@.service >/dev/null <<'EOF'
[Unit]
Description=Val %i (HTTP)
After=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/vals/%i
EnvironmentFile=/home/exedev/vals/%i/.env
ExecStart=/home/exedev/.deno/bin/deno run --allow-all --config=deno.json /home/exedev/vals-kit/run.ts http
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF
sudo tee /etc/systemd/system/val-cron@.service >/dev/null <<'EOF'
[Unit]
Description=Val %i (cron)

[Service]
Type=oneshot
User=exedev
WorkingDirectory=/home/exedev/vals/%i
EnvironmentFile=/home/exedev/vals/%i/.env
ExecStart=/home/exedev/.deno/bin/deno run --allow-all --config=deno.json /home/exedev/vals-kit/run.ts cron
EOF
sudo tee /etc/systemd/system/vals-mail.service >/dev/null <<'EOF'
[Unit]
Description=Email for vals
After=network-online.target

[Service]
User=exedev
ExecStart=/home/exedev/.deno/bin/deno run --allow-all /home/exedev/vals-kit/mail-router.ts
Restart=always

[Install]
WantedBy=multi-user.target
EOF
sudo tee /etc/systemd/system/vals-front.service >/dev/null <<'EOF'
[Unit]
Description=Front door for vals
After=network-online.target

[Service]
User=exedev
ExecStart=/home/exedev/.deno/bin/deno run --allow-all /home/exedev/vals-kit/front.ts
Restart=always

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now vals-front vals-mail

Export the code#

Save your API key where only you can read it, then export every val, or name the ones you want:

(umask 077; cat > ~/.valtown-api-key)   # paste the token, then Ctrl-D
deno run -A ~/vals-kit/export-vals.ts
deno run -A ~/vals-kit/export-vals.ts alice/guestbook alice/digest alice/inbox

Each val's files land in ~/valtown-export/<val>/. The script prints each trigger, and ~/valtown-export/vals.json keeps them with each val's variable names:

guestbook: 2 files
  http  main.ts https://alice--4f2e9c1a.web.val.run
digest: 2 files
  cron  main.ts
inbox: 2 files
  email main.ts alice-7b3d0e52@valtown.email

Val Town's API doesn't return cron schedules: read each one from the val's trigger settings.

Set up each val#

Copy a val into ~/vals, under a lowercase name of letters, digits, - and _ (it becomes the path and the email address), and point its std imports at the kit:

cp -r ~/valtown-export/guestbook ~/vals/guestbook
deno run -A ~/vals-kit/prepare.ts ~/vals/guestbook

prepare.ts ends with nothing left that uses Val Town, or lists lines to look at, such as imports of other vals (esm.town/v/alice/...; copy those vals in and import them by path) or *.val.run URLs.

Then write the val's .env. These variables tell the kit what to run; the val's own secrets go below them:

One val can have all three triggers. For the examples:

printf 'VAL_NAME=guestbook\nVAL_HTTP=main.ts\nPORT=8001\nPUBLIC=1\n' > ~/vals/guestbook/.env
printf 'VAL_NAME=digest\nVAL_CRON=main.ts\n' > ~/vals/digest/.env
printf 'VAL_NAME=inbox\nVAL_EMAIL=main.ts\n' > ~/vals/inbox/.env
chmod 600 ~/vals/*/.env

HTTP vals start with one command each:

sudo systemctl enable --now val-http@guestbook
sleep 5   # the first start downloads the val's packages
curl -s localhost:8001/

The handler gets a Request whose URL has the public host, as on val.run. Behind the front door at /guestbook/, paths still start at / (the prefix is in the X-Forwarded-Prefix header), which suits APIs and webhooks; a site with links like href="/about" wants its own domain in HOSTS.

Cron vals get a timer each. Translate the schedule:

sudo tee /etc/systemd/system/val-cron@digest.timer >/dev/null <<'EOF'
[Unit]
Description=Val digest (cron */15 * * * *)

[Timer]
OnCalendar=*:0/15
Persistent=true

[Install]
WantedBy=timers.target
EOF
systemd-analyze calendar '*:0/15'
sudo systemctl daemon-reload
sudo systemctl enable --now val-cron@digest.timer

systemd-analyze prints the next run, to check the translation. The handler gets { lastRunAt }, kept in data/cron-last-run. Persistent=true catches up a run missed while the VM was off.

Email vals need only their .env. Mail to inbox@<vm>.exe.xyz, or inbox+anything@, goes to ~/vals/inbox; the handler gets Val Town's Email object, with attachments as Files. Messages land in ~/Maildir/cur once handled, or ~/Maildir/failed. exe.dev takes messages up to 1 MB, with no spam filtering. The owner turns receiving on: ssh exe.dev share receive-email my-vals on.

Copy the data#

A val's SQLite database and blobs can only be read from inside the val, so the owner adds one file to each val that keeps data, in Val Town:

1. On the VM, make a token: (umask 077; openssl rand -hex 32 > ~/vals/guestbook/.export-token), and show it with cat.
2. In the val on Val Town, add an environment variable EXPORT_TOKEN with that value, and a new HTTP file named export-data.ts with the contents of export-data.ts. Copy the file's URL.

Then copy:

EXPORT_TOKEN=$(cat ~/vals/guestbook/.export-token) \
  deno run -A ~/vals-kit/pull-data.ts https://<export-data URL> ~/vals/guestbook

table entries: 1202 rows here, 1202 on Val Town
integrity_check: ok
blobs: 2 (12 bytes)
pull-data: all counts match

Tables, indexes, triggers, views, and AUTOINCREMENT counters come across with every value exact (64-bit integers, blobs, text with NULs). Virtual tables such as FTS are skipped and named: rebuild them from their source table. For the account-wide std/sqlite and std/blob, add --global and use ~/vals/.global as the directory; any one val's export-data.ts serves them. Run it again whenever you like: earlier files are kept as *.old.

Copy the secrets#

vals.json lists each val's variable names. Copy their values through the same file, without printing them:

EXPORT_TOKEN=$(cat ~/vals/guestbook/.export-token) \
  deno run -A ~/vals-kit/pull-env.ts https://<export-data URL> ~/vals/guestbook SLACK_TOKEN GITHUB_TOKEN

It won't copy EXPORT_TOKEN or Val Town's own valtown key. For a val without export-data.ts, copy values from its settings into .env with an editor: NAME=value, or NAME='value' with spaces or $. Restart the val after.

Keys the val only sends to one API can stay off the VM: an exe.dev HTTP proxy integration adds the key on the way out. On your computer:

ssh exe.dev integrations add http-proxy --name github \
  --target https://api.github.com --bearer "$GITHUB_TOKEN" --attach vm:my-vals

Then change the val to call https://github.int.exe.xyz/... with no key.

Check#

systemctl --no-pager is-active vals-front vals-mail 'val-http@*'
systemctl list-timers 'val-cron@*' --no-pager
for d in ~/vals/*/; do deno run -A ~/vals-kit/prepare.ts "$d" | tail -1; done

For the report, per val: its triggers, port and address, schedule and next run, email address, secrets named in vals.json but not in .env, whether its data is copied, and what prepare.ts still lists.

has no default export. Val Town runs a file's default export, or its only export. Add export default to the handler.

Email or Interval is not defined. Those are type names from Val Town's editor; deno run doesn't type-check, so this only comes up in deno check. Declare them in the file or drop the annotation.

An email val gets nothing. Run ssh exe.dev share receive-email my-vals on again, check that the val's directory name matches the address, and read journalctl -u vals-mail. exe.dev stops delivering if ~/Maildir/new passes 1,000 messages, so keep vals-mail running.

exe.dev email error. The gateway only sends to you, your team, people you share the VM with, and people who've emailed it. HTML is turned into plain text; from and custom headers are dropped.

std/openai says the model doesn't exist. Use a model the LLM gateway offers.

pull-data says MISMATCH. Something wrote during the copy: pause the val on Val Town and run it again.