Get a license key#
Currently IO is available in a private preview. Participants can download keys on the Preview page. 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 using Docker#
To run IO from its Docker image, save the following in a file named IO.sh and make it executable:
#!/bin/sh
#
# Run IO in a docker container.
# * Host networking allows IO and Envoy to bind to local ports.
# * The volume option allows IO to run in the current directory.
#
docker run \
--network host \
--volume $(pwd):/io \
agentio/io $@
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
-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 option to import this file. If you run with -x, IO will immediately exit after the configuration is read.
To read the license into an IO running with docker, copy your license.hcl to your run directory, and invoke IO with -c /io/license.hcl. This is because your run directory is mapped into the /io directory in the docker run invocation above.
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 .
Add an SSH key to allow remote login#
IO can display its 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 /io/user.hcl on the command line when you run IO. After you’ve done this once, your user description is stored in io.db 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 /io/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:
ssh -p 2200 localhost
(or replace localhost with the address of your 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