Skip to content

Using the service

We recommend using one of the following tools to send requests to the Flintlock server. There are GUI and CLI options.

hammertime

hammertime is a simple tool which gives a nice wrapper around what is essentially a curl. Use this if you need no bells and whistles and would rather manipulate your own json.

Example

hammertime create -a 192.168.1.66:9090 -n my-microvm -ns my-namespace

hammertime get -a 192.168.1.66:9090 -i <UUID>

hammertime create -a 192.168.1.66:9090 -f spec.json

hammertime delete -a 192.168.1.66:9090 --all

fl

fl aims to provide a fuller user experience, with formatted output and some extra features for handling your MicroVMs.

fl connects without TLS and doesn’t send an auth token, so use it with a flintlockd that was started with --insecure, as in this tutorial.

Example

Create a microVM. The kernel and root volume are OCI images, and fl uses these images by default if you leave the flags out:

fl microvm create --host 192.168.1.66:9090 --name my-microvm \
  --kernel-image ghcr.io/liquidmetal-dev/firecracker-kernel:6.1 \
  --root-image ghcr.io/liquidmetal-dev/ubuntu:24.04

The output includes the uid of the new microVM. List the microVMs on the host, or get one by its uid:

fl microvm get --host 192.168.1.66:9090

fl microvm get --host 192.168.1.66:9090 <uid>

Delete the microVM:

fl microvm delete --host 192.168.1.66:9090 <uid>

Run fl microvm create --help for the other options, including network interfaces, cloud-init metadata and extra volumes.

Running commands and SSH

fl can also run a command in a microVM, or open an SSH session to it, using the guest agent. To do this:

  1. Start flintlockd with --enable-exec-api for exec, --enable-ssh-proxy-api for SSH, or both.
  2. Create the microVM with --allow-guest-agent.
  3. Use a root image that runs the guest agent. For SSH, the image must also run sshd.
fl microvm exec --host 192.168.1.66:9090 <uid> -- uname -a

fl microvm ssh --host 192.168.1.66:9090 <uid> -- -l ubuntu

Arguments after -- in fl microvm ssh are passed to ssh.

grpc-client-cli

For the most bare-bones experience, use grpcurl and the ./hack/scripts/send.sh script.

Example

To create a MicroVM:

./hack/scripts/send.sh \
  --method CreateMicroVM

BloomRPC

BloomRPC is a GUI tool to test gRPC endpoints.

Import

To import Flintlock protos into the Bloom GUI:

  1. Click Import Paths on the left-hand menu bar and add <absolute-repo-path>/api to the list
  2. Click the import + button and select flintlock/api/services/microvm/v1alpha1/microvms.proto

All available endpoints will be visible in a nice tree view.

Example

To create a MircoVM, select the CreateMicroVM endpoint in the left-hand menu. Replace the sample request JSON in the left editor panel with this example. Click the green > in the centre of the screen. The response should come immediately.

In the terminal where you started the Flintlock server, you should see in the logs that the MircoVM has started.

To delete the MircoVM, select the DeleteMicroVM endpoint in the left-hand menu. Replace the sample request JSON in the left editor panel with this example. Take care to ensure the values match those of the MicroVM you created earlier. Click the green > in the centre of the screen. The response should come immediately.

Note: there are example payloads for other endpoints, but not all are implemented at present.