Get a license key#
Currently IO is available in a private preview. If you’re in it, you know how to get a key!
License keys are distributed in an HCL config file that’s usually named license.hcl. Its contents should look like this:
license = "YOUR-LICENSE-KEY"
Run IO interactively using Docker#
During the private preview, IO is distributed exclusively on Docker Hub as agentio/io.
To run IO interactively, save the following in a file named IO.sh and make it executable:
#!/bin/sh
#
# Interactively run IO in a docker container.
# * The TERM variable allows colors to be displayed correctly.
# * Host networking allows IO and Envoy to bind to local ports.
# * The volume option allows IO to run in the current directory.
#
docker run -ti -e "TERM=$TERM" \
--network host \
--volume $(pwd):/io \
agentio/io -i $@
Run IO from your terminal with ./IO.sh [options], where [options] are any additional options that you want to add.
If this is your first time running IO, you’ll find that you need a license key.
Activate IO with your license key#
When IO is run without a license, it prints the following:
$ ./IO.sh
Error: this private preview of io requires a license
Usage:
io [flags]
Flags:
--base-id int set the Envoy base ID
-c, --config strings load config file (can be used multiple times)
-x, --exit exit after importing config files
-h, --help help for io
-i, --interactive run with a local interactive console
-v, --version print version and exit
IO’s license key is stored in its local database (io.db), so once the license is applied, IO can be restarted without a key.
Run IO with the -c license.hcl option to import this file. If you run with -x, IO will immediately exit after the configuration is read.
When you run IO for the first time, it creates a SQLite database in a file named io.db and several log files. Because IO runs inside docker as root, these files are initially owned by root. You can fix that by using chown and chgrp to change the ownership of these files. Just run this in the directory where you are running IO:
chown -R $USER .
chgrp -R $USER .
Run IO as a daemon using Docker#
To run IO as a background process, save the following in a file named IO-background.sh and make it executable:
#!/bin/sh
#
# Run IO in a docker container.
# * The detach option runs the container in the background.
# * Host networking allows IO and Envoy to bind to local ports.
# * The volume option allows IO to run in the current directory.
#
docker run --detach \
--network host \
--volume $(pwd):/io \
agentio/io $@
Run IO from your terminal with ./IO-background.sh [options], where [options] are any additional options that you want to add. Remember that you’ll need to specify your license key at least once.
Add an SSH key to allow remote login#
When IO runs non-interactively, it can display the user interface over SSH.
For security, connections are only accepted from known users. To add a user, create an HCL config file, which here we call user.hcl:
user "USERID" {
name = "USERNAME"
public_key = "ssh-rsa ***KEYBYTES****************************************************************
***************************************************************************************************
***************************************************************************************************
***************************************************************************************************
***************************************************************************************************
***************************************************************************************************
***************************************************************************************************
***********************************************"
}
Here USERID should be a short user identifier (e.g. your lowercased first name), USERNAME is a printable (human-friendly) name, and the public_key value should be the contents of the public key file that you use for SSH (e.g. the contents of $HOME/.ssh/id_rsa.pub).
You can read this by specifying -c user.hcl on the command line when you run IO. After you’ve done this once, your user description is stored in SQLite and won’t need to be specified again.
If you want to add this user configuration while your IO is running in the background, just run ./IO.sh -c user.hcl -x in the directory where you are running IO. It will add the user to io.db and exit.
Connect to IO with SSH#
After you’ve added a user, you’ll be able to connect to your running IO with ssh -p 8022 localhost (or replace localhost with the address of the system running IO).
Stop your backgrounded IO#
If you’re running IO in the background with Docker, you can see your process with docker ps:
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1583170b4d3e agentio/io "/usr/local/bin/io io" 28 minutes ago Up 28 minutes mystifying_kilby
Then you can stop your IO with docker kill.
$ docker kill 1583
1583